Managed AgentsのMCP接続を設定しvaultで認証する手順

Claude Managed AgentsでMCPサーバーを使うときの設定は2箇所に分かれます。エージェント作成時にmcp_serversフィールドでサーバーの名前とURLを宣言し、セッション作成時にvault_idsで認証情報を渡します。この分離によって、認証トークンをエージェント定義に埋め込まずに済み、同じエージェントを複数ユーザーのセッションで使い回せます。

Managed AgentsのMCP接続は2段階に分かれている

Managed AgentsのMCP接続を理解する鍵は「宣言」と「認証」が別のタイミングで行われる点です。エージェント作成時にはサーバーのtype・name・urlだけを渡し、認証トークンは一切含めません。認証はセッション作成時、事前に登録したvault_idsを参照する形で供給されます。

この設計の狙いは、再利用可能なエージェント定義から秘密情報を切り離すことです。同じ「GitHub Assistant」エージェントを100人のユーザーが使っても、各セッションは自分のvaultを参照するだけで、エージェント定義そのものは1つのまま保てます。Managed AgentsのAPIリクエストはmanaged-agents-2026-04-01のベータヘッダーを必須とします(メモリーストア関連のエンドポイントだけagent-memory-2026-07-22)。SDKを使えば自動的に付与されるため、意識するのはcurlで直接叩く場合だけです。

エージェント作成時にmcp_serversでサーバーを宣言する

mcp_servers配列の各エントリーは1本の接続を表します。必須フィールドは3つです。

agent_response=$(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 @- <<'EOF'
{
  "name": "GitHub Assistant",
  "model": "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"}
  ]
}
EOF
)
agent_id=$(jq -r '.id' <<<"$agent_response")

宣言と参照は必ず対になっている必要があります。mcp_serversに書いたサーバーはtools配列のmcp_toolsetエントリーからmcp_server_nameで参照されていなければならず、逆に参照だけあってサーバー宣言が無い状態も許されません。どちらか片方だけの定義はAPIがエージェント作成そのものを拒否します。1エージェントにつき宣言できるMCPサーバーは最大20個で、名前は配列内で重複できません。

MCPツールセットの権限ポリシーは既定でalways_askです。ツールを呼び出すたびにユーザーの承認が必要になるため、自動化フローで使う場合はpermission policiesで緩める設定を検討します。

公開するツールをconfigsで絞り込む

mcp_toolsetエントリーはdefault_configとconfigs配列でツールの有効・無効を制御します。ビルトインのagent toolsetと違い、MCPツールのエントリーにtypeフィールドは不要です。web_searchやweb_fetchにあるようなドメイン制限の設定も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を置くだけで済みます。サーバー運営者が新しいツールを追加してもレビューするまで有効化されない、という運用がこのパターンで実現できます。

MCPツールの出力が100,000文字(おおよそ25,000トークン)を超えると、サンドボックス内のファイルへ自動的に書き出され、モデルにはファイルパス付きの切り詰められたプレビューだけが渡されます。巨大なレスポンスを返すツールを組み込むときはこの挙動を前提に設計します。

セッション作成時にvault_idsで認証情報を渡す

エージェント定義には認証トークンを一切含めません。セッションを作成するときにvault_idsを渡し、事前に登録したvaultから認証情報を供給します。

session_response=$(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 @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"]
}
EOF
)
session_id=$(jq -r '.id' <<<"$session_response")

認証情報とMCPサーバーの対応付けはURLで行われます。vaultに登録したstatic_bearerまたはmcp_oauthcredentialのmcp_server_urlが、mcp_serversで宣言したurlと一致すれば自動で紐付きます。両者のURLはマッチング前に正規化されます(スキームとホストを小文字化、デフォルトポートと末尾スラッシュを除去)。ホストの大文字小文字・デフォルトポート・末尾スラッシュの違いはマッチを妨げませんが、パス・サブドメイン・非デフォルトポートが異なる場合は別サーバー扱いになります。一致する認証情報が見つからなければ、接続は認証なしで試行されます。

接続失敗と認証失敗をどう見分けて復旧するか

セッション作成の時点では、MCPの疎通や認証情報は検証されません。サーバーが応答しない、あるいは認証情報を拒否した場合でも、セッションはそのまま開始され、他の機能とのやり取りは継続できます。問題が起きるとsession.errorイベントが発行され、影響を受けたmcp_server_nameとretry_statusが含まれます。

このイベントを受け取った側で、以降のやり取りをブロックするか、認証情報のローテーションを促すか、該当サーバーのツールを使わずセッションを継続させるかを判断します。接続の再試行は、次にsession.status_idleからsession.status_runningへ遷移するタイミングで自動的に行われます。「セッションが起動した=MCP接続が成功した」ではない点が、実装時に見落としやすい落とし穴です。起動直後のsession.errorを監視する処理を組み込まないと、認証切れのMCPサーバーをユーザーが気づかないまま使い続けることになります。SSEストリームを常時張らずに障害を検知したい場合は、Managed Agentsのwebhookでsessionイベントを購読する方法もあります。

接続できるMCPサーバーの種類を確認する

mcp_serversのurlにはどんなMCPサーバーでも指定できるわけではありません。Managed Agentsが接続できるのは、HTTPエンドポイントを公開するremote MCPサーバーか、MCP tunnels経由で公開したプライベートなMCPサーバーのどちらかです。社内ネットワークにしか置いていないMCPサーバーをそのままに書いても届きません。MCP tunnelsでトンネルを張るか、パブリックに到達可能なエンドポイントを用意する必要があります。

トランスポートはMCPプロトコルのstreamable HTTPが基本ですが、廃止予定のSSEトランスポートしかサポートしないサーバーでも、自動フォールバックによって動作します。古いMCPサーバー実装を接続する際に、トランスポート非対応で弾かれることは基本的にありません。

MCP tunnels自体はMCP connectorより制限の強いリサーチプレビュー段階にあり、使うには別途アクセス申請が必要です。すでに一般提供されているMCP connector機能とMCP tunnelsを同列に考えて申請なしで試そうとすると、権限不足で接続できずに詰まります。プライベートなMCPサーバーを繋ぐ計画があるなら、この申請フローが先に必要になることを見込んでおきます。

信頼できるMCPサーバーは確認なしで許可する

MCPツールセットの権限ポリシーは既定でalways_askです。これはMCPサーバー運営者が新しいツールを追加しても、承認なしにアプリケーション側で実行されないようにするための安全側の設定です。裏を返せば、自社が管理する信頼済みのMCPサーバーであっても、そのままでは毎回ユーザー承認を求められます。

自動化フローで確認を挟みたくないなら、mcp_toolsetエントリーのdefault_config.permission_policyにalways_allowを設定します。

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "default_config": {
    "permission_policy": { "type": "always_allow" }
  }
}

mcp_server_nameはmcp_servers配列に宣言したサーバーのnameと一致させます。個別のツールだけ確認を残したい場合は、configs配列の該当エントリーだけpermission_policyを上書きすれば、サーバー単位の既定値とツール単位の例外を両立できます。

Messages APIの汎用MCP connectorとは別物として扱う

Anthropicには、Messages APIから直接MCPサーバーを呼び出す汎用のMCP connector機能も別途あります。両者は名前が似ていますが、設計思想も設定場所も異なる別プロダクトです。

Managed AgentsのMCP接続をMessages APIのconnectorと同じ感覚で「リクエストのたびにトークンを渡すもの」と誤解すると、エージェント定義に認証情報を書き込もうとして詰まります。Managed Agentsでは認証はあくまでセッション側の責務です。Messages APIの手書きループから移行する際の設定対応表はManaged Agentsへの移行手順にまとめています。

まとめ

Managed AgentsでMCPサーバーを使うなら、まずエージェント作成時にmcp_serversと対になるmcp_toolsetを宣言し、公開するツールをconfigsで絞り込みます。認証はセッション作成時のvault_idsに切り出し、session.errorイベントで接続・認証の失敗を監視する設計にしておくと、認証切れに気づかないまま運用を続ける事故を防げます。すでにMessages APIの汎用MCP connectorを使っている場合は、宣言場所と認証タイミングが根本から違う点を踏まえて設定を作り直す必要があります。

Managed Agents全体の設計思想やセッション・ハーネス・サンドボックスの分離についてはManaged Agentsの設計思想で扱っています。