MCPコネクタ

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

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

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

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

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

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

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

ant apply github-assistant.md

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

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

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

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

次のステップ