Konektor MCP

Claude Managed Agents mendukung penghubungan server Model Context Protocol (MCP) ke agen Anda. Ini memberi agen akses ke alat eksternal, sumber data, dan layanan melalui protokol yang terstandarisasi.

Konfigurasi MCP dibagi menjadi dua langkah:

1. Pembuatan agen mendeklarasikan server MCP mana yang terhubung dengan agen, berdasarkan nama dan URL.
2. Pembuatan sesi menyediakan autentikasi untuk server tersebut dengan mereferensikan vault yang telah didaftarkan sebelumnya.

Pemisahan ini menjaga agar rahasia tidak tersimpan dalam definisi agen yang dapat digunakan kembali, sekaligus memungkinkan setiap sesi melakukan autentikasi dengan kredensialnya sendiri.



Mendeklarasikan server MCP pada agen

Tentukan server MCP dalam array mcp_servers saat membuat agen. Setiap server memerlukan type, name yang unik, dan url. Tidak ada token autentikasi yang diberikan pada tahap ini.

Setiap server yang dideklarasikan juga memerlukan entri mcp_toolset yang sesuai dalam array tools. Nilai mcp_server_name pada toolset harus cocok dengan name server.

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)



Referensi field mcp_servers

Setiap entri dalam array mcp_servers mendefinisikan satu koneksi.

Batasan:

• Sebuah agen dapat mendeklarasikan hingga 20 server MCP. Nama server harus unik dalam array.
• Setiap entri mcp_servers harus direferensikan oleh sebuah mcp_toolset dalam array tools, dan setiap mcp_toolset harus mereferensikan server yang telah dideklarasikan. API akan menolak definisi agen yang memiliki server tanpa referensi atau toolset yang menggantung.



Mengonfigurasi alat MCP mana yang tersedia

Entri mcp_toolset mendukung bentuk default_config dan configs yang sama seperti toolset agen bawaan, yang diterapkan pada alat yang diekspos oleh server MCP. Nilai name di setiap entri configs adalah nama alat polos seperti yang dilaporkan oleh server.

Secara default, semua alat yang diekspos oleh server MCP diaktifkan. Untuk mengaktifkan hanya alat tertentu, atur default_config.enabled ke false dan aktifkan secara eksplisit alat yang Anda inginkan:

{
  "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 }
  ]
}

Pola ini berguna ketika sebuah server mengekspos banyak alat tetapi agen hanya membutuhkan beberapa, atau ketika Anda ingin alat yang ditambahkan oleh operator server tetap nonaktif sampai Anda meninjaunya.

Untuk menonaktifkan alat tertentu sambil tetap mengaktifkan sisanya, hilangkan default_config dan atur enabled: false pada entri individual:

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

Lihat mengonfigurasi toolset untuk pola umum default_config / configs, dan izin toolset MCP untuk mengatur permission_policy pada alat MCP dan menangani permintaan konfirmasi.



Penanganan output alat MCP

Ketika output alat MCP melebihi 100.000 token, output tersebut secara otomatis ditulis ke sebuah file di sandbox. Model menerima pratinjau yang dipotong beserta path file dan dapat membaca konten lengkapnya dari sana.



Menyediakan autentikasi saat pembuatan sesi

Saat memulai sesi, berikan vault_ids untuk menyediakan kredensial bagi server MCP Anda. Vault adalah kumpulan kredensial yang Anda daftarkan sekali dan referensikan berdasarkan ID. Lihat Autentikasi dengan vault untuk cara membuat vault dan mengelola kredensial.

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

Kredensial dicocokkan berdasarkan URL, sehingga vault harus berisi kredensial yang mcp_server_url-nya persis cocok dengan url yang dideklarasikan di mcp_servers. Jika tidak ada yang cocok, koneksi akan dicoba tanpa autentikasi. Lihat Menambahkan kredensial untuk jenis kredensial static_bearer dan mcp_oauth.



Menangani kegagalan koneksi dan autentikasi

Pembuatan sesi tidak memvalidasi konektivitas atau kredensial MCP. Jika server MCP tidak dapat dijangkau atau menolak kredensial yang diberikan, sesi tetap dimulai dan interaksi tetap dimungkinkan. Sebuah event session.error akan dipancarkan dengan mcp_server_name dari server yang terpengaruh dan sebuah retry_status:

Anda dapat memutuskan apakah akan memblokir interaksi lebih lanjut karena error ini, memicu rotasi kredensial, atau membiarkan sesi berlanjut tanpa alat dari server yang terpengaruh. Koneksi akan dicoba ulang pada transisi berikutnya dari session.status_idle ke session.status_running.



Langkah selanjutnya