MCPコネクタ

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

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

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

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



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

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

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

AGENT_ID=$(ant beta:agents create --transform id --raw-output < github-assistant.agent.yaml)

name: GitHub Assistant
model:
  id: claude-opus-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_serversフィールドリファレンス

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

制約事項：

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



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

mcp_toolsetエントリは、MCPサーバーが公開するツールに適用されるdefault_configオブジェクトとconfigs配列をサポートしています。各configsエントリはname、enabled、permission_policyのみを受け付けます。組み込みエージェントツールセットのエントリとは異なり、MCPツールエントリはtypeフィールドを取らず、web_searchおよびweb_fetchで利用可能なWeb設定は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文字（約25,000トークン）を超えると、自動的にサンドボックス内のファイルに書き込まれます。モデルはファイルパスとともに切り詰められたプレビューを受け取り、そこから完全な内容を読み取ることができます。



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

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

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

認証情報はURLによって照合されるため、ボールトにはmcp_server_urlがmcp_serversで宣言されたurlと同じサーバーを参照する認証情報が含まれている必要があります。両方のURLは照合前に正規化されます（スキームとホストは小文字化され、デフォルトポートと末尾のスラッシュは削除されます）。そのため、ホストの大文字小文字の違い、デフォルトポート、末尾のスラッシュの有無は照合を妨げませんが、パス、サブドメイン、または非デフォルトポートが異なる場合は一致しません。一致するものがない場合、接続は認証なしで試行されます。static_bearerおよびmcp_oauth認証情報タイプについては、認証情報の追加を参照してください。



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

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

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



次のステップ