MCPコネクタ

Claude Managed Agentsは、Model Context Protocol (MCP)サーバーをエージェントに接続することをサポートしています。これにより、エージェントは標準化されたプロトコルを通じて外部ツール、データソース、サービスにアクセスできるようになります。

MCPの設定は2つのステップに分かれています。

1. エージェント作成では、エージェントが接続するMCPサーバーを名前とURLで宣言します。
2. セッション作成では、事前に登録されたvaultを参照することで、それらのサーバーの認証情報を提供します。

この分離により、再利用可能なエージェント定義からシークレットを除外しつつ、各セッションが独自の認証情報で認証できるようになります。



エージェントでMCPサーバーを宣言する

エージェントを作成する際に、mcp_servers配列でMCPサーバーを指定します。各サーバーにはtype、一意のname、およびurlが必要です。この段階では認証トークンは提供しません。

宣言された各サーバーには、tools配列内に対応するmcp_toolsetエントリも必要です。ツールセットのmcp_server_nameはサーバーのnameと一致する必要があります。

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)



mcp_serversフィールドリファレンス

mcp_servers配列の各エントリは1つの接続を定義します。

制約：

• エージェントは最大20個のMCPサーバーを宣言できます。サーバー名は配列内で一意である必要があります。
• すべてのmcp_serversエントリはtools配列内のmcp_toolsetによって参照される必要があり、すべてのmcp_toolsetは宣言されたサーバーを参照する必要があります。APIは、参照されていないサーバーや対応するサーバーのないツールセットを含むエージェント定義を拒否します。



利用可能なMCPツールを設定する

mcp_toolsetエントリは、組み込みのエージェントツールセットと同じdefault_configおよびconfigsの形式をサポートしており、MCPサーバーが公開するツールに適用されます。各configsエントリのnameは、サーバーが報告するツール名そのものです。

デフォルトでは、MCPサーバーが公開するすべてのツールが有効になっています。特定のツールのみを有効にするには、default_config.enabledをfalseに設定し、必要なツールを明示的に有効にします。

{
  "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を設定します。

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

一般的なdefault_config / configsパターンについてはツールセットの設定を、MCPツールへのpermission_policyの設定と確認リクエストの処理についてはMCPツールセットの権限を参照してください。



MCPツール出力の処理

MCPツールの出力が100,000トークンを超える場合、自動的にサンドボックス内のファイルに書き込まれます。モデルはファイルパスを含む切り詰められたプレビューを受け取り、そこから完全な内容を読み取ることができます。



セッション作成時に認証情報を提供する

セッションを開始する際に、vault_idsを渡してMCPサーバーの認証情報を提供します。Vaultは、一度登録してIDで参照する認証情報のコレクションです。Vaultの作成と認証情報の管理方法については、Vaultで認証するを参照してください。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

認証情報はURLで照合されるため、Vaultにはmcp_serversで宣言されたurlと完全に一致するmcp_server_urlを持つ認証情報が含まれている必要があります。一致するものがない場合、接続は認証なしで試行されます。static_bearerおよびmcp_oauth認証情報タイプについては、認証情報を追加するを参照してください。



接続および認証の失敗を処理する

セッション作成時にはMCPの接続性や認証情報は検証されません。MCPサーバーに到達できない場合や、提供された認証情報が拒否された場合でも、セッションは開始され、対話は引き続き可能です。影響を受けたサーバーのmcp_server_nameとretry_statusを含むsession.errorイベントが発行されます。

このエラーに対して、それ以降の対話をブロックするか、認証情報のローテーションをトリガーするか、影響を受けたサーバーのツールなしでセッションを続行させるかを決定できます。接続は、次にsession.status_idleからsession.status_runningへの遷移が発生した際に再試行されます。



次のステップ