Coworkカスタムコネクタ自作ガイド — リモートMCPで社内システムに接続する

Coworkディレクトリに無い社内システムやニッチなSaaSは、リモートMCPサーバーを自分で立てて「カスタムコネクタ」として登録すれば接続できます。Team/Enterpriseプランではオーナーが組織に登録し、メンバーが個別に認証する2段構成です。この記事ではサーバー側の技術要件、登録手順、接続できないときの切り分け方を順に扱います。自社で立てずに業務自動化基盤をそのまま公開する例は、Workato MCPのClaude接続にあります。

Coworkのカスタムコネクタとは何か

カスタムコネクタとは、URLを登録するだけで接続できるリモートMCPサーバーの登録機能です。Model Context Protocol(MCP)はAnthropicが策定したオープンな標準規格で、AIアプリケーションがツールやデータに接続するための共通仕様です。以前はMCPサーバーがローカル(利用者のノートPC上)でしか動きませんでしたが、現在はインターネット越しに通信するリモートMCPサーバーを開発者が自分でホストできます。

Coworkに限らず、claude.ai・Claude Desktop・モバイルアプリを含むすべてのClaudeクライアントで、カスタムコネクタは同じ仕組みで動きます。Free・Pro・Max・Team・Enterpriseの全プランで利用でき、Freeプランだけ登録数が1件に制限されます。プリビルドconnectorやディレクトリ掲載サービスとの使い分けはClaude CoworkのConnectors一覧で扱っています。Splunk公式のMCP Serverを個別に繋ぐ具体例はClaudeとSplunkを連携してSPLクエリを自然言語で実行するで扱っています。

自作する前に確認すること — 接続はAnthropicのクラウドから発信される

自作コネクタで最初につまずくのがネットワークの向きです。Coworkはローカルで動くアプリですが、カスタムコネクタを追加すると、ClaudeはAnthropicのクラウドインフラからあなたのリモートMCPサーバーに接続します。手元の端末からではありません。これはCoworkとClaude Desktopでも同様で、両者がローカルアプリであることとは関係ありません。

つまり、サーバーはAnthropicのIPレンジからパブリックインターネット経由で到達可能である必要があります。社内ネットワークの内側、VPNの背後、ファイアウォールで塞がれた場所に置いたサーバーは、自分のマシンからは届いても接続できません。社内ネットワークに置く場合の選択肢は2つあります。

トンネル経由のサーバーも、メンバーから見れば普通のカスタムコネクタとして表示されます。トンネルの各サーバーに割り当てられるのはtunnel.anthropic.com配下のホスト名で、Claude以外からの接続は受け付けません。自分の端末からcurlで確認することはできず、Claudeから使って検証します。

手順1: リモートMCPサーバーを用意する

サーバー実装から始める場合、TypeScript SDKとPython SDKにサーバー実装のサンプルが用意されています。ゼロから作るのが手間な場合は、Claude Codeに公式のmcp-server-devプラグインを入れると、対話形式でサーバーの実装・テスト・パッケージ化まで進められます。ホスティングにはCloudflareのように、オートスケーリングとOAuth管理を備えたリモートMCPサーバー向けのプラットフォームも使えます。ゼロからサーバーを組み立てる手順はMCPサーバー自作ガイドにまとめています。

対応しているプロトコル機能とサーバー側の技術仕様は次の通りです。

表の列名はclaude.aiとDesktopです。ただし上限は、ホスト型のClaudeアプリ(claude.ai・Desktop・モバイル・Cowork)とClaude Codeで分かれるとされています。Coworkも前者の値を前提に、巨大なレスポンスや長時間の処理を避けたツール設計にしておくと安全です。

手順2: 認証方式を選ぶ

サーバー側で選べる認証方式は6種類あります。どれを選ぶかで、追加の申請が要るかどうかが変わります。

サーバー側の方式は、登録ダイアログの選択肢に対応します。登録する側は、まず「Authentication」でサインインの出し方を選びます。

• Sign in now: 利用前に、各ユーザーがサーバーのOAuthフローでサインインする
• Sign in when needed: 認証なしで接続し、サーバーが求めた時点でサインインを促す
• No sign-in: URLを知っていれば誰でも使える。APIキーで守る場合もこれを選び、キーは「Request headers」に入れる

OAuthを選んだときは、続けて「OAuth client」でClaudeの名乗り方を決めます。

自作側から見ると、registration_endpointを出せない認可サーバーでもCIMDに対応すれば1番目の方式で動きます。CIMDをClaudeが選ぶのは、認可サーバーのメタデータが次の2つを満たすときだけです。1つ目は"client_id_metadata_document_supported": trueがあること。2つ目はtoken_endpoint_auth_methods_supportedに"none"が含まれていることです。どちらかが欠けるとDCRにフォールバックします。

固定のAPIキーやbearerトークンで動く社内ツールには、リクエストヘッダー認証(static_headers)があります。個人ごとのサインインは要らず、組織の全員が同じ認証情報を共有する前提です。サーバー側では、このキーでどのユーザーが呼んだかを判別できません。ユーザー本人の権限で動かしたいツールなら、OAuthを選びます。

ヘッダー認証の入力欄は、ベータとして一部の組織にだけ出ます。「Request headers」セクションが見えなければ、その組織はまだ対象外です。入力のルールは次のとおりです。

• ヘッダーは最大4つまで。名前は一覧から選ぶか、「Custom header」で入力する
• authorization・x-api-key・x-auth-tokenはすべてのコネクタで使える。それ以外の名前はAnthropicの承認が先に要り、未承認の名前は保存時に拒否される
• 値は入力したまま送られ、スキームは補われない。Bearer your-tokenならAuthorization: Bearer your-token、your-tokenだけならAuthorization: your-tokenになる
• OAuthと併用できるが、OAuth接続ではAuthorizationをヘッダーとして設定できない

OAuth認証の仕組みをさらに深く知りたい場合はリモートMCPのOAuth認証を参照してください。

サーバーを実装したら、登録前にMCP Inspectorで認可フローを検証しておくと、組織登録後のトラブルを減らせます。認可サーバーとのやり取り(discovery・クライアント登録・トークン取得)をInspector上で一通り通します。そのあとclaude mcp addでClaude Codeに一時的に追加し、/mcpコマンドで疎通と認証が通ることを確認します。この2段階を踏んでから組織への登録に進むと、原因の切り分けが楽になります。

手順3: Team/Enterpriseプランで組織に登録する

Team/Enterpriseプランでは、コネクタを組織に追加できるのはOwner(Primary Ownerを含む)だけです。追加された後、メンバーは個別に認証して使い始めます。これにより、Claudeがアクセスできるのは各利用者が実際に権限を持つ範囲のツールとデータに限られます。

Enterpriseプランでは、組織のライブラリを管理できるカスタムロールのメンバーも追加できます。それ以外のメンバーは自分では追加できないので、Ownerへの依頼になります。

登録したカスタムコネクタのURLが、Connectorsディレクトリに載っているサービス(Workatoのワークスペースなど)のドメインと一致することがあります。この場合、「Custom」ではなくそのサービス名とブランディングで表示されます。中身は自分で登録した接続先のままなので、削除して登録し直す必要はありません。

手順4: Pro/Maxプランで個人アカウントに追加する

個人のPro/Maxプランであれば、組織の承認なしに自分で追加できます。

1. Customize > Connectorsに移動する
2. 「Add custom connector」をクリックする
3. リモートMCPサーバーのURLを入力する
4. 必要に応じてOAuth認証情報を指定する
5. 「Add」で確定する

追加後は、チャット入力欄下部の「+」ボタンから「Connectors」を開くと、会話ごとに有効/無効を切り替えるトグルが表示されます。使わないコネクタはここで切っておけます。特定のツールだけ止めたいときは、「Customize > Connectors」でコネクタを選び、そのツールの権限を「Blocked」にします。

よくあるつまずき — 接続できない・認証が通らないとき

接続エラーには2種類あります。「Couldn't reach the MCP server」と「Authorization with the MCP server failed」です。どちらも複数の原因をひとまとめにした表示なので、症状だけで原因を決めつけず、順番に切り分けます。

まず確認すること: 接続に失敗すると、エラーのトーストとページURLにofid_から始まる参照IDが表示されます。原因が特定できない場合、このIDを控えておくと調査が早くなります。例は.../customize/connectors?step=start_error&flow_id=ofid_d32594c73257a651のようなURLです。参照IDには有効期限があるため、失敗した直後に控えてください。報告先はanthropics/claude-ai-mcpのGitHub issuesで、IDとサーバーURL、サーバー側のOAuthログの時刻を添えます。

「Couldn't reach the MCP server」の主な原因

1. ホスト名がプライベートIPを指している — claude.aiはAnthropicのインフラから、パブリックインターネット経由でサーバーに到達します。名前解決の結果がプライベートアドレス(10.0.0.0/8など)やキャリアグレードNAT、ループバック、リンクローカルのいずれかであれば、Claudeはリクエストを送る前に接続を拒否します。公開DNSにAレコードが無く、AAAAレコードだけのホスト名にも届きません。コネクタはIPv4のみに対応しています。手元の端末やClaude Codeでは繋がるのにclaude.aiだけ繋がらない場合、社内DNSと外部DNSで解決結果が違う「スプリットホライズンDNS」を疑ってください
2. ファイアウォールやWAFがAnthropicの通信を止めている — CDNやWAF、bot対策のルールがリクエストをブロックしていないか、エッジのログで403や429を確認します
3. サーバーのURLが別ホストへリダイレクトしている — 登録したURLが301/302などで別ホストへ転送される設定だと、Authorizationヘッダーが落とされます。標準的なHTTPクライアントが、リダイレクト時にそうするためです。転送先は認証なしのリクエストを受け取り401を返します。結果として「認証に失敗した」というエラーになります
4. OAuthのdiscoveryが失敗している — 401レスポンスに、resource_metadataを指すWWW-Authenticateヘッダーが無いとします。その場合、Claudeは/.well-known/配下の標準パスを探しにいきます。そこも404なら、認可サーバーの場所自体を特定できません

curl -i https://your-server.example.com/.well-known/oauth-protected-resource
curl -i https://your-server.example.com/.well-known/oauth-authorization-server
curl -i https://your-server.example.com/.well-known/openid-configuration

上記をパブリックなネットワークから実行します。protected resource metadataが200とJSONを返すかを確認してください。authorization server metadataは、2つのエンドポイントのどちらかが200を返せば足ります。多くのホスト型IDプロバイダーは/.well-known/openid-configurationだけを提供します。Auth0・Okta・Microsoft Entra・Keycloak・Supabase Authがその例です。もう一方が404でも問題ありません。

「Authorization with the MCP server failed」の主な原因

• issuerの不一致: 認可サーバーのメタデータに書かれたissuerと、実際にトークンへ署名している発行者が食い違っている
• audienceの不一致: ClaudeはRFC 8707のresourceパラメータに、MCPサーバーURLの正規形(スキームとホストは小文字、末尾スラッシュなし)を載せて送ります。認可サーバー側がこの正規形をそのままaudとして検証できないと失敗します
• PKCE未対応: Claudeはすべての認可リクエストにcode_challenge_method=S256のPKCEを付けます。認可サーバーがS256のPKCEに対応していないと、トークンエンドポイントで失敗します
• トークンエンドポイントの応答が遅い: Claudeはdiscovery・登録・トークン取得のエンドポイントに最大10秒、リフレッシュトークンには最大30秒待ちます。この時間内にレスポンスが返らないと、サーバー側で最終的に成功していても失敗扱いになります
• フォームボディを読めない: /tokenはClaudeからapplication/x-www-form-urlencodedで呼ばれます。JSONしか解析しないフレームワークの既定のままだと、415 Unsupported Media Typeを返します。/registerだけはapplication/jsonなので、パーサーを共用しないでください
• リフレッシュトークンの失効の返し方: 失効時はinvalid_requestや独自コードでなく、RFC 6749どおりinvalid_grantを返します。DCRとCIMDではClaudeは公開クライアント扱いなので、リフレッシュトークンはローテーションが前提です。更新時は、旧トークンを無効にする同じ応答で新しいものを返します
• リダイレクトURIの未登録: Cowork・claude.ai・Desktop・モバイルは、https://claude.ai/api/mcp/auth_callbackを固定のコールバックにします。自前のクライアントIDを使うなら、認可サーバー側にこの値を完全一致で登録します。Claude Codeはポートが毎回変わるループバック(http://localhost:3118/callbackなど)です。併用するなら、localhostと127.0.0.1の両方を、ポートを無視して照合します

Claudeがサインインを始めるきっかけは401です。200にWWW-Authenticateヘッダーを付けても無視されます。また、メタデータのauthorization_serversが複数あっても、使われるのは先頭の1件だけです。認可サーバー側のホストにもAnthropicの発信元から届く必要があるので、IdPの前段のWAFで止まっていても同じ症状になります。

Microsoft Entra IDを認可サーバーに使っている場合に固有の落とし穴もあります。トークン要求がAADSTS9010010で失敗するときは、原因はアプリ登録側にあります。Claudeが送るresourceの値(MCPサーバーURLそのもの)が、「Application ID URI」に登録されていないのです。既定のapi://{client-id}だけでは足りず、MCPサーバーのURLをパスまで含めてApplication ID URIに追加する必要があります。

「Unexpected error while invoking tool」は別の切り分け

接続もサインインも成功しているのに、このメッセージにツール名が続く場合は、リクエストはサーバーに届いています。サーバーがそのツール呼び出しにエラー結果を返したという意味で、接続障害ではないためofid_の参照IDも出ません。

同じ呼び出しをMCP Inspectorで実行して、Claudeが報告するエラーと結果を比べます。次にサーバーのログで、ツールハンドラーのエラーと、全ユーザーに出るのか特定のアカウントだけかを確認します。それでも分からなければ、ツール名と失敗の時刻(UTC)、コネクタのURLを添えてGitHub issuesに報告します。

診断チェックリスト

問い合わせる前に、次の順で確認すると原因の切り分けが早くなります。

1. パブリックなネットワークからdig +short your-server.example.comを実行し、グローバルにルーティング可能なアドレスが返るか確認する
2. curl -i https://your-server.example.com/your-mcp-pathを実行し、レスポンスが返るか確認する(401や405は正常、タイムアウトや接続拒否は異常)
3. curl -sIでリダイレクトの有無を確認する。別ホストへの3xxが返るなら、転送先のURLを登録し直す
4. エッジのログで403/429が出ていないか確認し、必要ならAnthropicの公開IPレンジを許可リストに追加する
5. discoveryメタデータの2つのエンドポイントをcurlで確認する
6. 認可サーバーとMCPサーバーのホストが異なる場合、認可サーバー側もAnthropicの発信元から到達可能か確認する
7. 再現させてofid_の参照IDを控える

Claude Code側での接続確認や切り分けの手順はMCPサーバーに接続できないときの切り分け手順で扱っています。

セキュリティ上、自作コネクタで気をつけること

カスタムコネクタはAnthropicが検証していない任意のサービスへの接続を許可する機能です。接続後、Claudeはそのサービスにアクセスし、権限の範囲内で操作を実行できるようになります。信頼できる組織が構築・運用しているサーバーにのみ接続し、OAuthの同意画面で要求される権限スコープは接続のたびに確認してください。想定外のスコープを要求された場合は許可しない判断も必要です。

悪意のあるMCPサーバーは、隠された指示でClaudeに意図しない操作をさせようとするプロンプトインジェクションを仕込むことがあります。Claudeには対策が組み込まれていますが、ツールの入出力には注意を払い、信頼できるサーバーにのみ接続する原則は変わりません。サーバー開発者が後からツールの挙動を変更する可能性もあるため、想定外の動きが無いか継続的に確認する運用が安全です。悪意のあるMCPサーバーを見つけた場合は、Anthropicの脆弱性報告プログラムへの報告が案内されています。接続後のデータ取り扱いはCoworkセキュリティ — データはどこに置かれ誰が触れるかで詳しく扱っています。

まとめ

登録できるかどうかより、Anthropicのクラウドから届く場所にサーバーがあるかで成否が決まります。社内ネットワークの中なら、IPの許可リストか、Enterpriseに限るMCPトンネルかを先に決めてください。登録後に変えられるのは名前とURLだけなので、認証方式は登録前に固めておくと、メンバー全員の再接続を避けられます。