--- title: MCPコネクタ url: https://platform.claude.com/docs/ja/managed-agents/mcp-connector description: MCPサーバーをエージェントに接続して、外部ツールやデータソースにアクセスできるようにします。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Claude Managed Agentsは、[Model Context Protocol（MCP）](https://modelcontextprotocol.io)サーバーをエージェントに接続することをサポートしています。これにより、エージェントは標準化されたプロトコルを通じて外部ツール、データソース、サービスにアクセスできるようになります。 MCPの設定は2つのステップに分かれています。 1. **エージェントの作成**では、エージェントが接続するMCPサーバーを名前とURLで宣言します。 2. **セッションの作成**では、事前に登録されたvault（ボールト）を参照することで、それらのサーバーの認証情報を提供します（[vaultによる認証](https://platform.claude.com/docs/ja/managed-agents/vaults)を参照してください）。 この分離により、再利用可能なエージェント定義からシークレットを排除しつつ、各セッションが独自の認証情報で認証できるようになります。 ## エージェントでMCPサーバーを宣言する エージェントを作成する際に、`mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)配列でMCPサーバーを指定します。各サーバーには、`type` (csharp, go: `Type`)、一意の`name` (csharp, go: `Name`)、および`url` (csharp: `Url`; go: `URL`)が必要です。この段階では認証トークンは提供しません。 宣言した各サーバーには、`tools` (csharp, go: `Tools`)配列内に対応する`mcp_toolset`エントリも必要です。ツールセットの`mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`)は、サーバーの`name` (csharp, go: `Name`)と一致している必要があります。 ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "GitHub Assistant", "model": "claude-opus-5-5", "mcp_servers": [ { "type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/" } ], "tools": [ {"type": "agent_toolset_20260401"}, {"type": "mcp_toolset", "mcp_server_name": "github"} ] }' ``` ```bash CLI ant apply github-assistant.md ``` ```markdown --- name: GitHub Assistant model: claude-opus-5-5 mcp_servers: - type: url name: github url: https://api.githubcopilot.com/mcp/ tools: - type: agent_toolset_20260401 - type: mcp_toolset mcp_server_name: github --- ``` ```python Python agent = client.beta.agents.create( name="GitHub Assistant", model="claude-opus-5-5", mcp_servers=[ { "type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/", }, ], tools=[ {"type": "agent_toolset_20260401"}, {"type": "mcp_toolset", "mcp_server_name": "github"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "GitHub Assistant", model: "claude-opus-5-5", mcp_servers: [ { type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" } ], tools: [ { type: "agent_toolset_20260401" }, { type: "mcp_toolset", mcp_server_name: "github" } ] }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "GitHub Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, McpServers = [ new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" }, ], Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, new BetaManagedAgentsMcpToolsetParams { Type = "mcp_toolset", McpServerName = "github" }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "GitHub Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://api.githubcopilot.com/mcp/", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", }, }, }, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("GitHub Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addMcpServer( BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") .url("https://api.githubcopilot.com/mcp/") .build() ) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .addTool( BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .build() ) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'GitHub Assistant', model: 'claude-opus-5-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/', ), ], tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsMCPToolsetParams::with( type: 'mcp_toolset', mcpServerName: 'github', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "GitHub Assistant", model: "claude-opus-5-5", mcp_servers: [ { type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" } ], tools: [ {type: "agent_toolset_20260401"}, {type: "mcp_toolset", mcp_server_name: "github"} ] ) ``` MCPツールセットのデフォルトの権限ポリシーは`always_ask`であり、各ツール呼び出しの前にユーザーの承認が必要です。この動作を設定するには、[権限ポリシー](https://platform.claude.com/docs/ja/managed-agents/permission-policies)を参照してください。 ### `mcp_servers`フィールドリファレンス `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)配列の各エントリは、1つの接続を定義します。 | フィールド | 説明 | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (csharp, go: `Type`) | 必須。`"url"`である必要があります。 | | `name` (csharp, go: `Name`) | 必須。エージェント内でこのサーバーを一意に識別する名前（1〜255文字）。`tools` (csharp, go: `Tools`)配列内の`mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`)として使用され、[セッションイベントストリーム](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming)のMCPツールイベントにも表示されます。 | | `url` (csharp: `Url`; go: `URL`) | 必須。リモートMCPサーバーのエンドポイント（最大2,048文字）。トランスポート要件については、[サポートされているMCPサーバータイプ](https://platform.claude.com/docs/ja/managed-agents/reference#supported-mcp-server-types)を参照してください。 | 制約： * エージェントは最大20個のMCPサーバーを宣言できます。サーバー名は配列内で一意である必要があります。 * すべての`mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)エントリは`tools` (csharp, go: `Tools`)配列内の`mcp_toolset`から参照されている必要があり、すべての`mcp_toolset`は宣言済みのサーバーを参照している必要があります。APIは、参照されていないサーバーや参照先のないツールセットを含むエージェント定義を拒否します。 ## 利用可能なMCPツールを設定する `mcp_toolset`エントリは、MCPサーバーが公開するツールに適用される`default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`)オブジェクトと`configs` (csharp, go: `Configs`)配列をサポートしています。各`configs` (csharp, go: `Configs`)エントリが受け付けるのは、`name` (csharp, go: `Name`)、`enabled` (csharp, go: `Enabled`)、`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)のみです。組み込みのエージェントツールセットのエントリとは異なり、MCPツールのエントリは`type` (csharp, go: `Type`)フィールドを取らず、`web_search`および`web_fetch`で利用できる[Web設定](https://platform.claude.com/docs/ja/managed-agents/tools-web-restrictions#settings)はMCPツールには適用されません。各`configs` (csharp, go: `Configs`)エントリの`name` (csharp, go: `Name`)は、サーバーが報告するそのままのツール名です。 デフォルトでは、MCPサーバーが公開するすべてのツールが有効になっています。特定のツールのみを有効にするには、`default_config.enabled`を`false`に設定し、必要なツールを明示的に有効にします。 ```json { "type": "mcp_toolset", "mcp_server_name": "github", "default_config": { "enabled": false }, "configs": [ { "name": "get_issue", "enabled": true }, { "name": "list_issues", "enabled": true }, { "name": "add_issue_comment", "enabled": true } ] } ``` このパターンは、サーバーが多数のツールを公開しているがエージェントが必要とするのはごく一部である場合や、サーバー運営者によって追加されたツールをレビューするまで無効のままにしておきたい場合に便利です。 残りのツールを有効にしたまま特定のツールを無効にするには、`default_config`を省略し、個々のエントリに`enabled: false`を設定します。 ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` 一般的な`default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`)パターンについては[ツールセットの設定](https://platform.claude.com/docs/ja/managed-agents/tools#configuring-the-toolset)を、MCPツールでの`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)の設定と確認リクエストの処理については[MCPツールセットの権限](https://platform.claude.com/docs/ja/managed-agents/permission-policies#mcp-toolset-permissions)を参照してください。 ### MCPツール出力の処理 MCPツールの出力が100,000文字（約25,000トークン）を超えると、自動的にサンドボックス内のファイルに書き込まれます。モデルはファイルパスを含む切り詰められたプレビューを受け取り、そこから完全な内容を読み取ることができます。 ## セッション作成時に認証情報を提供する セッションを開始する際に、`vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`)を渡してMCPサーバーの認証情報を提供します。vaultは、一度登録してIDで参照する認証情報のコレクションです。vaultの作成方法と認証情報の管理については、[vaultによる認証](https://platform.claude.com/docs/ja/managed-agents/vaults)を参照してください。 `limited`の[環境](https://platform.claude.com/docs/ja/managed-agents/environments#networking)では、エージェントが宣言したMCPサーバーのホストが`allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)に含まれていない場合、セッションの作成は400エラーで失敗します。環境のネットワーク設定で`allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`)を`true`に設定すると、このチェックは無効になります。 ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$agent_id"'", "environment_id": "'"$environment_id"'", "vault_ids": ["'"$vault_id"'"] }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" \ --vault-id "$VAULT_ID" ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, vault_ids=[vault.id], ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, VaultIds = [vault.ID], }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, EnvironmentID: environment.ID, VaultIDs: []string{vault.ID}, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create( SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .addVaultId(vault.id()) .build() ); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, vaultIDs: [$vault->id], ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] ) ``` 認証情報はURLで照合されるため、vaultには、`mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)で宣言された`url` (csharp: `Url`; go: `URL`)と同じサーバーを指す`mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`)を持つ認証情報が含まれている必要があります。両方のURLは照合前に正規化される（スキームとホストは小文字化され、デフォルトポートと末尾のスラッシュは除去される）ため、ホストの大文字・小文字の違い、デフォルトポート、末尾のスラッシュの有無は照合を妨げません。一方、パス、サブドメイン、またはデフォルト以外のポートが異なる場合は一致しません。一致するものがない場合、接続は認証なしで試行されます。`static_bearer`および`mcp_oauth`の認証情報タイプについては、[認証情報を追加する](https://platform.claude.com/docs/ja/managed-agents/vaults#add-a-credential)を参照してください。 ### 接続および認証の失敗を処理する セッションの作成時には、MCPの接続性や認証情報は検証されません。ただし、宣言された各サーバーのホストが環境のネットワーク設定に照らしてチェックされます。`limited`環境では、[セッション作成時に認証情報を提供する](https://platform.claude.com/docs/ja/managed-agents/mcp-connector#provide-authentication-at-session-creation)で説明したとおり、ホストが許可されていない場合、セッションの作成は400エラーで失敗します。MCPサーバーに到達できない場合や、提供された認証情報が拒否された場合でも、セッションは開始され、対話は引き続き可能です。影響を受けたサーバーの`mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`)と`retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`)を含む[`session.error`](https://platform.claude.com/docs/ja/managed-agents/reference#event-types)イベントが発行されます。 | エラータイプ | 意味 | | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `mcp_connection_failed_error` | MCPサーバーに到達できませんでした（ネットワークエラー、タイムアウト、または認証以外のHTTPエラー）。 | | `mcp_authentication_failed_error` | MCPサーバーとの認証に失敗しました。サーバーがアタッチされたvaultの認証情報を拒否した、一致する認証情報が設定されていない状態でサーバーが認証を要求した、またはOAuthトークンのリフレッシュに失敗した場合です。 | このエラーに対して、以降の対話をブロックするか、認証情報のローテーションをトリガーするか、影響を受けたサーバーのツールなしでセッションを続行させるかを決定できます。接続は、次回の`session.status_idle`から`session.status_running`への遷移時に再試行されます。 ## 次のステップ エージェントツールとMCPツールがいつ実行されるかを制御します。 イベントの送信、レスポンスのストリーミング、実行中のセッションの中断やリダイレクトを行います。 リモートMCPサーバーのトランスポート要件。