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

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

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

「宣言」と「認証」は別のタイミングで行います。

狙いは、再利用可能なエージェント定義から秘密情報を切り離すことです。同じ「GitHub Assistant」を100人が使っても、各セッションは自分のvaultを参照するだけで、エージェント定義は1つのまま保てます。

Managed AgentsのAPIリクエストはmanaged-agents-2026-04-01のベータヘッダーを必須とします。SDKは自動で付与するので、意識するのはcurlで直接叩く場合だけです。メモリーストアのエンドポイントだけはagent-memory-2026-07-22を使い、両方を同じリクエストに混ぜると400になります。

エージェント作成時に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-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がエージェント作成そのものを拒否します。

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

mcp_toolsetエントリーはdefault_configとconfigs配列でツールの有効・無効を制御します。configsの各エントリーが受け付けるのはname・enabled・permission_policyの3つだけです。nameはサーバーが報告するそのままのツール名を書きます。

ビルトインの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を置きます。

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

MCPツールの出力が100,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のmcp_server_urlがmcp_serversのurlと一致すれば、自動で紐付きます。両者のURLはマッチング前に正規化され、スキームとホストは小文字に、デフォルトポートと末尾スラッシュは除去されます。

つまり、ホストの大文字小文字・デフォルトポート・末尾スラッシュの違いはマッチを妨げません。パス・サブドメイン・非デフォルトポートが違えば別サーバー扱いです。

vault側の制約と運用上の挙動

credentialの登録まわりには、API側で決まっている制約があります。

• mcp_server_urlは、vault内の有効なcredentialの中で一意でなければならず、重複登録は409になります
• mcp_server_urlは作成後に変更できません。変えたいときは古いcredentialをアーカイブして作り直します
• vault自体をアーカイブすると、そのvaultを参照する新しいセッションは失敗します。すでに動いているセッションは続行します
• 複数のvaultを渡して同じURLのcredentialが重なった場合は、最初に一致したvaultが使われます
• vaultとcredentialはワークスペース単位なので、そのワークスペースのAPIキーなら誰でもセッション作成時に参照できます。権限を取り消すには、vaultかcredentialを削除します

credentialは登録時には検証されず、ランタイムではじめて使われます。ローテーションやアーカイブは定期的に再解決され、実行中のセッションにも再起動なしで反映されます。

セッションが失敗する・つながらないときの切り分け

症状ごとに、疑う場所が変わります。

セッション作成が400で返る

環境のネットワークがlimitedのとき、エージェントのMCPサーバーは既定でブロックされます。allow_mcp_servers: trueを設定するか、各サーバーのホストをallowed_hostsに並べない限り、セッション作成は400で失敗します。

APIで環境を作るときにnetworkingを省くとunrestrictedになる点にも注意が必要です。意図せず全開放のまま動かすことを避けるなら、環境の作り方をManaged Agentsの環境構築で確かめてください。

セッションは起動したがMCPツールが動かない

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

イベントを受け取った側で、以降のやり取りをブロックするか、認証情報のローテーションを促すか、該当サーバーのツールを使わずに続けるかを決めます。接続の再試行は、session.status_idleからsession.status_runningへ遷移するたびに自動で行われます。

「セッションが起動した=MCP接続が成功した」ではありません。起動直後のsession.errorを監視しないと、認証切れのMCPサーバーを気づかないまま使い続けることになります。イベントの受け取り方はManaged Agentsのイベントストリームが詳しいです。

認証が必要なサーバーに認証なしで当たっている

vaultに一致するcredentialが無いと、接続は認証なしで試行され、サーバーが認証を要求すればmcp_authentication_failed_errorになります。URLの不一致(パスやサブドメインの違い)が原因のことが多いので、mcp_server_urlとurlを並べて見比べます。

OAuthトークンの更新だけが失敗する場合は、Webhookのvault_credential.refresh_failedで検知できます。Webhookの購読はManaged Agentsのwebhookにまとめています。

接続できるMCPサーバーの種類

mcp_serversのurlにはどんなMCPサーバーでも指定できるわけではありません。接続できるのは、HTTPエンドポイントを公開するremote MCPサーバーか、MCP tunnels経由で公開したプライベートなMCPサーバーのどちらかです。社内ネットワークにしか置いていないサーバーは、そのままでは届きません。

トランスポートはstreamable HTTPが基本です。廃止予定のSSEトランスポートしか対応しないサーバーも、自動フォールバックで動きます。

MCP tunnelsはリサーチプレビューで、使うには別途アクセス申請が必要です。プライベートなMCPサーバーを繋ぐ計画があるなら、この申請が先に要ります。

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

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

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

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

個別のツールだけ確認を残したい場合は、configsの該当エントリーだけpermission_policyを上書きします。サーバー単位の既定値とツール単位の例外を両立できます。詳細はpermission policiesにあります。

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

Messages APIにも、MCPサーバーを直接呼び出すMCP connectorがあります。名前は似ていますが、認証の渡し方も設定の置き場所も違います。

リクエストのたびにトークンを渡す感覚でManaged Agentsを設定すると、エージェント定義に認証情報を書き込もうとして詰まります。

同じMCPサーバーに複数の接続経路がある例は、Postman MCPサーバーの使い方がConnectorと手動接続の違いで扱っています。Messages APIの手書きループから移行するときの設定対応表はManaged Agentsへの移行手順にあります。

まとめ

新規に組むなら、最初に決めるのはトークンの持ち主です。ユーザーやセッションごとに変わるならvault、リクエストごとに渡す単発の呼び出しならMessages APIのconnectorが合います。

動かないときは症状で戻る節が決まります。セッション作成が400ならネットワーク設定の節、起動後にツールが動かないならsession.errorの種別の節です。

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