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 ke agen, berdasarkan nama dan URL.
2. Pembuatan sesi menyediakan autentikasi untuk server tersebut dengan mereferensikan vault yang telah didaftarkan sebelumnya (lihat Autentikasi dengan vault).

Pemisahan ini menjaga rahasia tetap di luar 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 --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



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 dengan server yang tidak direferensikan atau toolset yang menggantung.



Mengonfigurasi alat MCP mana yang tersedia

Entri mcp_toolset mendukung objek default_config dan array configs, yang diterapkan pada alat yang diekspos oleh server MCP. Setiap entri configs hanya menerima name, enabled, dan permission_policy. Tidak seperti entri dalam toolset agen bawaan, entri alat MCP tidak menerima field type, dan pengaturan web yang tersedia pada web_search dan web_fetch tidak berlaku untuk alat MCP. Nilai name dalam setiap entri configs adalah nama alat polos sebagaimana 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 karakter (sekitar 25.000 token), output tersebut secara otomatis ditulis ke file dalam 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 merujuk ke server yang sama dengan url yang dideklarasikan dalam mcp_servers. Kedua URL dinormalisasi sebelum pencocokan (scheme dan host diubah menjadi huruf kecil, port default dan garis miring di akhir dihapus), sehingga perbedaan dalam kapitalisasi host, port default, atau garis miring di akhir tidak mencegah kecocokan; path, subdomain, atau port non-default yang berbeda akan mencegahnya. Jika tidak ada yang cocok, koneksi akan dicoba tanpa autentikasi. Lihat Menambahkan kredensial untuk tipe 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. 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 pada error ini, memicu rotasi kredensial, atau membiarkan sesi berlanjut tanpa alat dari server yang terpengaruh. Koneksi akan dicoba ulang pada transisi session.status_idle ke session.status_running berikutnya.



Langkah selanjutnya