Halaman ini mencakup konfigurasi MCP untuk Agent SDK. Untuk menambahkan server MCP ke Claude Code CLI sehingga dimuat di setiap proyek, lihat Cakupan instalasi MCP.
Quickstart
Contoh ini terhubung ke server MCP dokumentasi Claude Code menggunakan transport HTTP dan menggunakanallowedTools dengan wildcard untuk mengizinkan semua alat dari server.
Tambahkan server MCP
Anda dapat mengonfigurasi server MCP dalam kode saat memanggilquery(), atau dalam file .mcp.json yang dimuat melalui settingSources.
Dalam kode
Teruskan server MCP langsung dalam opsimcpServers:
Dari file konfigurasi
Buat file.mcp.json di root proyek Anda. File ini diambil ketika sumber pengaturan project diaktifkan, yang merupakan default untuk opsi query(). Jika Anda menetapkan settingSources secara eksplisit, sertakan "project" agar file ini dimuat:
Izinkan alat MCP
Alat MCP memerlukan izin eksplisit sebelum Claude dapat menggunakannya. Tanpa izin, Claude akan melihat bahwa alat tersedia tetapi tidak akan dapat memanggilnya.Konvensi penamaan alat
Alat MCP mengikuti pola penamaanmcp__<server-name>__<tool-name>. Misalnya, server GitHub bernama "github" dengan alat list_issues menjadi mcp__github__list_issues.
Persetujuan otomatis dengan allowedTools
GunakanallowedTools untuk secara otomatis menyetujui alat MCP tertentu sehingga Claude dapat menggunakannya tanpa permintaan izin:
*) memungkinkan Anda mengizinkan semua alat dari server tanpa mencantumkan masing-masing secara individual.
Lebih suka
allowedTools daripada mode izin untuk akses MCP. permissionMode: "acceptEdits" tidak secara otomatis menyetujui alat MCP (hanya edit file dan perintah Bash filesystem). permissionMode: "bypassPermissions" secara otomatis menyetujui alat MCP tetapi juga menonaktifkan sebagian besar prompt keamanan lainnya, yang lebih luas dari yang diperlukan; lihat Bagaimana izin dievaluasi untuk prompt yang tetap ada. Wildcard dalam allowedTools memberikan akses ke server MCP yang Anda inginkan dan tidak lebih. Lihat Mode izin untuk perbandingan lengkap.Temukan alat yang tersedia
Untuk melihat alat apa yang disediakan server MCP, periksa dokumentasi server atau terhubung ke server dan periksa pesan initsystem:
Jenis transport
Server MCP berkomunikasi dengan agen Anda menggunakan protokol transport yang berbeda. Periksa dokumentasi server untuk melihat transport mana yang didukungnya:- Jika dokumen memberi Anda perintah untuk dijalankan (seperti
npx @modelcontextprotocol/server-github), gunakan stdio - Jika dokumen memberi Anda URL, gunakan HTTP atau SSE
- Jika Anda membangun alat Anda sendiri dalam kode, gunakan server MCP SDK
Server stdio
Proses lokal yang berkomunikasi melalui stdin/stdout. Gunakan ini untuk server MCP yang Anda jalankan di mesin yang sama:- Dalam kode
- .mcp.json
Server HTTP/SSE
Gunakan HTTP atau SSE untuk server MCP yang dihosting cloud dan API jarak jauh:- Dalam kode
- .mcp.json
"type": "http" sebagai gantinya. Dalam file konfigurasi .mcp.json dan JSON lainnya, "streamable-http" diterima sebagai alias untuk "http". Opsi mcpServers pemrograman hanya menerima "http".
Server MCP SDK
Tentukan alat khusus langsung dalam kode aplikasi Anda daripada menjalankan proses server terpisah. Lihat panduan alat khusus untuk detail implementasi.Pencarian alat MCP
Ketika Anda memiliki banyak alat MCP yang dikonfigurasi, definisi alat dapat mengonsumsi bagian signifikan dari jendela konteks Anda. Pencarian alat mengatasi ini dengan menahan definisi alat dari konteks dan memuat hanya yang Claude butuhkan untuk setiap giliran. Pencarian alat diaktifkan secara default. Lihat Pencarian alat untuk opsi konfigurasi dan detail. Untuk detail lebih lanjut, termasuk praktik terbaik dan menggunakan pencarian alat dengan alat SDK khusus, lihat panduan pencarian alat.Autentikasi
Sebagian besar server MCP memerlukan autentikasi untuk mengakses layanan eksternal. Teruskan kredensial melalui variabel lingkungan dalam konfigurasi server.Teruskan kredensial melalui variabel lingkungan
Gunakan bidangenv untuk meneruskan kunci API, token, dan kredensial lainnya ke server MCP:
- Dalam kode
- .mcp.json
Header HTTP untuk server jarak jauh
Untuk server HTTP dan SSE, teruskan header autentikasi langsung dalam konfigurasi server:- Dalam kode
- .mcp.json
Autentikasi OAuth2
Spesifikasi MCP mendukung OAuth 2.1 untuk otorisasi. SDK tidak membuka browser atau menjalankan alur OAuth interaktif. Ketika server yang dikonfigurasi mengembalikan tantangan otorisasi dan tidak ada token yang disimpan tersedia, jalankan agen berlanjut tanpa alat server tersebut, dan server dilaporkan dengan statusneeds-auth dalam array mcp_servers dari pesan inisialisasi sistem. Periksa array tersebut saat startup jika agen Anda bergantung pada server tertentu yang terhubung.
Untuk menyediakan kredensial, selesaikan alur OAuth dalam aplikasi Anda sendiri dan teruskan token akses yang dihasilkan dalam headers server:
Contoh
Daftar masalah dari repositori
Contoh ini terhubung ke server MCP GitHub untuk mencantumkan masalah terbaru. Contoh ini mencakup logging debug untuk memverifikasi koneksi MCP dan panggilan alat. Sebelum menjalankan, buat token akses pribadi GitHub dengan cakupanrepo dan atur sebagai variabel lingkungan:
Tanyakan database
Contoh ini menggunakan server MCP Postgres untuk menanyakan database. String koneksi diteruskan sebagai argumen ke server. Agen secara otomatis menemukan skema database, menulis kueri SQL, dan mengembalikan hasilnya:Penanganan kesalahan
Server MCP dapat gagal terhubung karena berbagai alasan: proses server mungkin tidak terinstal, kredensial mungkin tidak valid, atau server jarak jauh mungkin tidak dapat dijangkau. SDK mengirimkan pesansystem dengan subtype init di awal setiap kueri. Pesan ini mencakup status koneksi untuk setiap server MCP. Periksa bidang status untuk mendeteksi kegagalan koneksi sebelum agen mulai bekerja:
Troubleshooting
Server menunjukkan status “failed”
Periksa pesaninit untuk melihat server mana yang gagal terhubung:
- Variabel lingkungan yang hilang: Pastikan token dan kredensial yang diperlukan diatur. Untuk server stdio, periksa bidang
envcocok dengan apa yang diharapkan server. - Server tidak terinstal: Untuk perintah
npx, verifikasi paket ada dan Node.js ada di PATH Anda. - String koneksi tidak valid: Untuk server database, verifikasi format string koneksi dan bahwa database dapat diakses.
- Masalah jaringan: Untuk server HTTP/SSE jarak jauh, periksa URL dapat dijangkau dan firewall apa pun memungkinkan koneksi.
Alat tidak dipanggil
Jika Claude melihat alat tetapi tidak menggunakannya, periksa bahwa Anda telah memberikan izin denganallowedTools:
Timeout koneksi
Koneksi server MCP mengalami timeout setelah 30 detik secara default. Jika server Anda membutuhkan waktu lebih lama untuk memulai, koneksi akan gagal. Naikkan batasnya dengan variabel lingkunganMCP_TIMEOUT, dalam milidetik. Untuk server yang memerlukan waktu startup lebih lama, pertimbangkan juga:
- Menggunakan server yang lebih ringan jika tersedia
- Pre-warming server sebelum memulai agen Anda
- Memeriksa log server untuk penyebab inisialisasi lambat
Output alat melebihi token maksimal yang diizinkan
SDK menerapkan batas output MCP yang sama dengan Claude Code. Ketika hasil alat lebih besar dari 25.000 token, output lengkap disimpan ke file dan hasil alat diganti dengan pesan kesalahan yang menyebutkan jalur file, sehingga agen dapat membaca output kembali dalam porsi. Naikkan batasnya dengan variabel lingkunganMAX_MCP_OUTPUT_TOKENS. Lihat MCP output limits and warnings untuk perilaku lengkap, termasuk bagaimana server dapat mendeklarasikan batas per-alat yang lebih tinggi.
Sumber daya terkait
- Panduan alat khusus: Bangun server MCP Anda sendiri yang berjalan in-process dengan aplikasi SDK Anda
- Izin: Kontrol alat MCP mana yang dapat digunakan agen Anda dengan
allowedToolsdandisallowedTools - Batas output MCP dan peringatan: Bagaimana SDK menangani hasil alat yang melebihi
MAX_MCP_OUTPUT_TOKENS, termasuk fallback persist-to-disk dan anotasi per-alatanthropic/maxResultSizeChars - Referensi SDK TypeScript: Referensi API lengkap termasuk opsi konfigurasi MCP
- Referensi SDK Python: Referensi API lengkap termasuk opsi konfigurasi MCP
- Direktori server MCP: Jelajahi server MCP yang tersedia untuk database, API, dan lainnya