SpyBara
Go Premium

agent-sdk/mcp.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 245 additions and 157 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58

Hubungkan ke alat eksternal dengan MCP

Konfigurasi server MCP untuk memperluas agen Anda dengan alat eksternal. Mencakup jenis transport, pencarian alat untuk set alat besar, autentikasi, dan penanganan kesalahan.

Model Context Protocol (MCP) adalah standar terbuka untuk menghubungkan agen AI ke alat eksternal dan sumber data. Dengan MCP, agen Anda dapat menanyakan database, mengintegrasikan dengan API seperti Slack dan GitHub, dan terhubung ke layanan lain tanpa menulis implementasi alat khusus.

Server MCP dapat berjalan sebagai proses lokal, terhubung melalui HTTP, atau dieksekusi langsung dalam aplikasi SDK Anda.

Quickstart

Contoh ini terhubung ke server MCP dokumentasi Claude Code menggunakan transport HTTP dan menggunakan allowedTools dengan wildcard untuk mengizinkan semua alat dari server.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
options: {
mcpServers: {
"claude-code-docs": {
type: "http",
url: "https://code.claude.com/docs/mcp"
}
},
allowedTools: ["mcp__claude-code-docs__*"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Agen terhubung ke server dokumentasi, mencari informasi tentang hooks, dan mengembalikan hasilnya.

Tambahkan server MCP

Anda dapat mengonfigurasi server MCP dalam kode saat memanggil query(), atau dalam file .mcp.json yang dimuat melalui settingSources.

Dalam kode

Teruskan server MCP secara langsung dalam opsi mcpServers. Contoh ini memulai server MCP filesystem lokal untuk /Users/me/projects. Ganti jalur tersebut dengan direktori di mesin Anda:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "List files in my project",
options: {
mcpServers: {
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}
},
allowedTools: ["mcp__filesystem__*"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

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. Ganti /Users/me/projects dengan direktori di mesin Anda:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Waktu koneksi

Claude Code mendaftarkan server yang Anda berikan dalam options.mcpServers saat startup dan mengirimkan pesan init setelah penundaan putaran pertama, jika ada, terselesaikan. Tanpa options.mcpServers, Claude Code menunggu 2 detik untuk server yang tertunda sebelum putaran pertama, jadi server yang dimuat dari file pengaturan seperti .mcp.json biasanya menunjukkan pending saat init. Ketika setiap server options.mcpServers terhubung, dan apakah itu menunda putaran pertama, tergantung pada jenisnya:

Jenis server Menunda putaran pertama? Batas waktu tunggu putaran pertama
Server stdio, atau server HTTP/SSE tanpa daftar alat yang di-cache Ya, sampai terhubung MCP_TIMEOUT, 30 detik secara default; koneksi gagal pada batas waktu tersebut
Server jarak jauh dengan daftar alat yang di-cache, disimpan oleh Claude Code dari koneksi sebelumnya Tidak; alat yang di-cache tersedia dari putaran pertama Tidak ada; terhubung pada panggilan alat pertamanya, dan koneksi tertunda tersebut memiliki batas waktu sendiri
Server SDK dalam proses Tidak; tidak pernah menunda putaran pertama Tidak ada

Untuk memblokir startup itu sendiri pada fase terpisah yang lebih awal daripada penundaan putaran pertama, sebelum pesan init dikirim:

  • Atur MCP_CONNECTION_NONBLOCKING ke 0 untuk memblokir seluruh batch koneksi. Claude Code membatasi penundaan tersebut pada 5 detik secara default. Sesuaikan batas dengan variabel lingkungan MCP_CONNECT_TIMEOUT_MS, dalam milidetik. Server yang masih tertunda pada batas waktu tersebut terus terhubung di latar belakang.
  • Atur alwaysLoad: true pada konfigurasi server untuk membuat alatnya tersedia pada skema lengkap mereka pada putaran pertama, dikecualikan dari penundaan pencarian alat. Claude Code menunggu saat startup untuk alat server tersebut, dibatasi pada batas waktu yang sama, sementara server lain terus terhubung di latar belakang; server jarak jauh dengan daftar alat yang di-cache menyediakannya tanpa terhubung, sesuai tabel di atas.

Pesan system dengan subtipe init melaporkan status setiap server pada saat pesan tersebut dikirim; lihat Penanganan kesalahan untuk membaca status tersebut.

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 penamaan mcp__<server-name>__<tool-name>. Misalnya, server GitHub bernama "github" dengan alat list_issues menjadi mcp__github__list_issues.

Auto-approve dengan allowedTools

Gunakan allowedTools untuk auto-approve alat MCP tertentu sehingga Claude dapat menggunakannya tanpa prompt izin:

const _ = {
options: {
mcpServers: {
// your servers
},
allowedTools: [
"mcp__github__*", // All tools from the github server
"mcp__db__query", // Only the query tool from db server
"mcp__slack__send_message" // Only send_message from slack server
]
}
};

Wildcard (*) memungkinkan Anda untuk mengizinkan semua alat dari server tanpa mencantumkan masing-masing secara individual.

Temukan alat yang tersedia

Untuk melihat alat apa yang disediakan server MCP, periksa dokumentasi server atau inspeksi array tools dalam pesan init system. Nama alat MCP dimulai dengan mcp__.

Claude Code memancarkan pesan init setelah penundaan koneksi giliran pertama untuk server yang dilewatkan dalam options.mcpServers, jadi array tools mencantumkan alat mcp__ dari setiap server yang telah terhubung pada saat itu, ditambah alat dari server dengan daftar alat yang di-cache, yang terhubung pada penggunaan pertama. Alat dari server lain yang belum terhubung tidak ada; lihat Penanganan kesalahan untuk membaca status setiap server.

Filter ini mencetak nama alat MCP:

import { query } from "@anthropic-ai/claude-agent-sdk";

const options = {
mcpServers: {
// your servers
},
};

for await (const message of query({ prompt: "...", options })) {
if (message.type === "system" && message.subtype === "init") {
const mcpTools = message.tools.filter((name) => name.startsWith("mcp__"));
console.log("Available MCP tools:", mcpTools);
}
}

Anda juga dapat meminta Claude untuk mencantumkan alat yang tersedia dari server.

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-filesystem), 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. Untuk bentuk .mcp.json, gunakan bidang yang sama seperti yang ditunjukkan di Dari file konfigurasi. Dalam kode, teruskan perintah dan argumennya. Ganti /Users/me/projects dengan direktori di mesin Anda:

const _ = {
options: {
mcpServers: {
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}
},
allowedTools: ["mcp__filesystem__read_file", "mcp__filesystem__list_directory"]
}
};

Server HTTP/SSE

Gunakan HTTP atau SSE untuk server MCP yang dihosting di cloud dan API jarak jauh. Untuk bentuk .mcp.json, gunakan bidang yang sama seperti contoh di Header HTTP untuk server jarak jauh, dengan "type": "sse" untuk server SSE. Dalam kode, teruskan URL server:

const _ = {
options: {
mcpServers: {
"remote-api": {
type: "sse",
url: "https://api.example.com/mcp/sse",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__remote-api__*"]
}
};

Untuk transport HTTP yang dapat dialirkan, gunakan "type": "http" sebagai gantinya. Dalam file konfigurasi .mcp.json dan JSON lainnya, "streamable-http" diterima sebagai alias untuk "http". Tipe McpHttpServerConfig SDK hanya mendeklarasikan "http", jadi gunakan "http" untuk server yang Anda teruskan dalam kode.

Server MCP SDK

Tentukan alat khusus langsung dalam kode aplikasi Anda alih-alih menjalankan proses server terpisah. Lihat panduan alat khusus untuk detail implementasi.

Server MCP SDK yang didaftarkan oleh permintaan kontrol initialize mulai terhubung segera setelah Claude Code memproses permintaan.

Ketika Anda memiliki banyak tool MCP yang dikonfigurasi, definisi tool dapat mengonsumsi sebagian signifikan dari jendela konteks Anda. Pencarian tool mengatasi ini dengan menahan definisi tool dari konteks dan memuat hanya yang Claude butuhkan untuk setiap giliran.

Pencarian tool diaktifkan secara default. Lihat Pencarian tool untuk opsi konfigurasi, praktik terbaik, dan menggunakan pencarian tool dengan tool SDK kustom.

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 field env untuk meneruskan kunci API, token, dan kredensial lainnya ke server MCP:

const _ = {
options: {
mcpServers: {
"api-server": {
command: "npx",
args: ["-y", "@your-org/api-mcp-server"],
env: {
API_KEY: process.env.API_KEY
}
}
},
allowedTools: ["mcp__api-server__*"]
}
};

Header HTTP untuk server jarak jauh

Untuk server HTTP dan SSE, teruskan header autentikasi langsung dalam konfigurasi server:

const _ = {
options: {
mcpServers: {
"secure-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__secure-api__*"]
}
};

Untuk contoh kerja lengkap dari server jarak jauh yang diautentikasi dengan header, lihat Daftar masalah dari repositori.

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 melaporkan status needs-auth. Array mcp_servers dari pesan inisialisasi sistem mungkin masih menunjukkan pending untuk server tersebut saat dipancarkan. Untuk mengonfirmasi apakah server memerlukan kredensial, polling mcpServerStatus() dalam SDK TypeScript atau get_mcp_status() dalam Python.

Untuk menyediakan kredensial, selesaikan alur OAuth dalam aplikasi Anda sendiri dan teruskan token akses yang dihasilkan dalam headers server:

// Setelah menyelesaikan alur OAuth dalam aplikasi Anda.
// Implementasikan getAccessTokenFromOAuthFlow untuk penyedia OAuth Anda.
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
mcpServers: {
"oauth-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${accessToken}`
}
}
},
allowedTools: ["mcp__oauth-api__*"]
};

Contoh

Daftar masalah dari repositori

Contoh ini terhubung ke server MCP GitHub jarak jauh untuk mencantumkan masalah terbaru. Contoh ini mencakup logging debug untuk memverifikasi koneksi MCP dan panggilan alat.

Sebelum menjalankan, buat token akses pribadi GitHub dengan akses baca ke repositori yang ingin Anda kueri dan atur sebagai variabel lingkungan:

export GITHUB_TOKEN=YOUR_GITHUB_PAT

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "List the 3 most recent issues in anthropics/claude-code",
options: {
mcpServers: {
github: {
type: "http",
url: "https://api.githubcopilot.com/mcp/",
headers: {
Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
}
}
},
allowedTools: ["mcp__github__list_issues"]
}
})) {
// Verify MCP server connected successfully
if (message.type === "system" && message.subtype === "init") {
console.log("MCP servers:", message.mcp_servers);
}

// Log when Claude calls an MCP tool
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
console.log("MCP tool called:", block.name);
}
}
}

// Print the final result
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Pada baris MCP servers:, status sebesar connected untuk github mengkonfirmasi token berfungsi. Jika Claude Code memiliki daftar alat yang di-cache untuk server, status dapat membaca pending sebagai gantinya dan server terhubung pada panggilan alat pertamanya. Jika statusnya adalah failed atau needs-auth, lihat Penanganan kesalahan sebelum mempercayai hasilnya, karena Claude dapat kembali ke alat bawaan ketika server tidak tersedia.

Kueri basis data

Contoh ini menggunakan DBHub untuk mengueri basis data Postgres. Agen secara otomatis menemukan skema basis data, menulis kueri SQL, dan mengembalikan hasilnya.

Alat execute_sql DBHub menjalankan SQL apa pun yang dikeluarkan agen, termasuk penulisan, kecuali Anda membatasinya. Mengatur readonly = true dalam file konfigurasi DBHub membuat DBHub menolak pernyataan INSERT, UPDATE, DELETE, dan DDL, sehingga contoh tidak dapat memodifikasi data Anda bahkan jika agen mengeluarkan penulisan. DBHub menyelesaikan ${DATABASE_URL} dari lingkungan proses ketika memuat konfigurasi, sehingga string koneksi tetap keluar dari file. Buat dbhub.toml ini di sebelah skrip Anda:

[[sources]]
id = "production"
dsn = "${DATABASE_URL}"

[[tools]]
name = "execute_sql"
source = "production"
readonly = true

Skrip kemudian menunjukkan DBHub ke file konfigurasi alih-alih melewatkan string koneksi secara langsung. Sebelum menjalankan, atur variabel lingkungan DATABASE_URL ke string koneksi Anda. Ganti nilai placeholder dengan detail basis data Anda sendiri:

export DATABASE_URL=postgresql://user:password@localhost:5432/mydb

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
// Natural language query - Claude writes the SQL
prompt: "How many users signed up last week? Break it down by day.",
options: {
mcpServers: {
postgres: {
command: "npx",
// dbhub.toml sets readonly = true, so execute_sql rejects writes
args: ["-y", "@bytebase/dbhub", "--config", "dbhub.toml"]
}
},
allowedTools: ["mcp__postgres__execute_sql"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

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.

Claude Code mengirimkan pesan system dengan subtype init di awal setiap kueri. Pesan ini mencakup status koneksi untuk setiap server MCP. Bidang status dapat berupa "pending", "connected", "failed", "needs-auth", atau "disabled". Claude Code mengirimkan pesan init setelah waktu tunggu koneksi putaran pertama untuk server yang dilewatkan dalam options.mcpServers, jadi server seperti itu yang terhubung dalam waktu tunggu menunjukkan "connected".

Dalam pesan init, jangan perlakukan "pending" sebagai kegagalan dengan sendirinya. Ini dapat berarti salah satu dari ini:

Periksa "failed" atau "needs-auth" untuk mendeteksi server yang tidak akan dapat digunakan:

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
for await (const message of query({
prompt: "Process data",
options: {
mcpServers: {
// Replace dataServer with your server configuration
"data-processor": dataServer
}
}
})) {
if (message.type === "system" && message.subtype === "init") {
const unavailableServers = message.mcp_servers.filter(
(s) => s.status === "failed" || s.status === "needs-auth"
);

if (unavailableServers.length > 0) {
console.warn("Unavailable MCP servers:", unavailableServers);
}
}

if (message.type === "result" && message.subtype === "error_during_execution") {
console.error("Execution failed");
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branch above has
// already run; a failure to start or reach the Claude Code process
// yields no result message. MCP servers that fail to connect don't
// throw: use the status check above, and note that servers still
// "pending" at init need a later status check.
console.log(`Session ended with an error: ${error}`);
}

Status server jarak jauh juga dapat berubah setelah melaporkan "connected". Ketika koneksi ke server itu terputus di tengah sesi, Claude Code memindahkan server kembali ke "pending" sambil menghubungkan kembali. Panggilan mcpServerStatus() yang lebih baru dalam TypeScript, atau ClaudeSDKClient.get_mcp_status() dalam Python, kemudian dapat melaporkan "pending" untuk server yang Anda lihat terhubung sebelumnya, tanpa perubahan konfigurasi di pihak Anda.

Setelah lima upaya penghubungan kembali gagal, server melaporkan "failed", atau "needs-auth" ketika perlu diotorisasi lagi. Untuk mencoba lagi secara manual, panggil reconnectMcpServer() dalam TypeScript atau ClaudeSDKClient.reconnect_mcp_server() dalam Python.

Troubleshooting

Server menunjukkan status "failed"

Periksa pesan init untuk melihat server mana yang gagal terhubung:

if (message.type === "system" && message.subtype === "init") {
for (const server of message.mcp_servers) {
if (server.status === "failed") {
console.error(`Server ${server.name} failed to connect`);
}
}
}

Status "pending" tidak berarti server gagal. Lihat Error handling untuk kasus-kasus yang dicakupnya saat init. Untuk mendapatkan status yang diperbarui nanti dalam sesi, panggil metode mcpServerStatus() query di TypeScript SDK, atau ClaudeSDKClient.get_mcp_status() di Python.

Penyebab umum:

  • Variabel lingkungan yang hilang: Pastikan token dan kredensial yang diperlukan telah diatur. Untuk server stdio, periksa bahwa field env cocok dengan apa yang diharapkan server.
  • Server tidak terinstal: Untuk perintah npx, verifikasi bahwa paket ada dan Node.js berada 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 bahwa URL dapat dijangkau dan firewall apa pun memungkinkan koneksi.

Tools tidak dipanggil

Jika Claude melihat tools tetapi tidak menggunakannya, periksa bahwa Anda telah memberikan izin dengan allowedTools:

const _ = {
options: {
mcpServers: {
// your servers
},
allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
}
};

Connection timeouts

Koneksi server MCP habis waktu setelah 30 detik secara default. Untuk mengubah berapa lama panggilan tool yang sedang berjalan dapat memakan waktu, atur MCP_TOOL_TIMEOUT. Jika server Anda membutuhkan waktu lebih lama untuk memulai, koneksi gagal. Naikkan batas koneksi dengan variabel lingkungan MCP_TIMEOUT, dalam milidetik. Untuk server yang membutuhkan lebih banyak waktu startup, pertimbangkan juga:

  • Menggunakan server yang lebih ringan jika tersedia
  • Pre-warming server sebelum memulai agent Anda
  • Memeriksa log server untuk penyebab inisialisasi yang lambat

Di TypeScript, Anda dapat mengatur batas panggilan tool untuk SDK MCP server tunggal dengan melewatkan timeout ke createSdkMcpServer().

Tool output melebihi token maksimal yang diizinkan

SDK menerapkan batas output MCP yang sama dengan Claude Code. Ketika hasil tool lebih besar dari 25.000 token, output lengkap disimpan ke file dan hasil tool diganti dengan pesan kesalahan yang menyebutkan jalur file, sehingga agent dapat membaca output kembali dalam porsi. Naikkan batas dengan variabel lingkungan MAX_MCP_OUTPUT_TOKENS. Lihat MCP output limits and warnings untuk perilaku lengkap, termasuk bagaimana server dapat mendeklarasikan batas per-tool yang lebih tinggi dengan anotasi anthropic/maxResultSizeChars.

  • Panduan alat kustom: Bangun server MCP Anda sendiri yang berjalan dalam proses dengan aplikasi SDK Anda
  • Izin: Kontrol alat MCP mana yang dapat digunakan agen Anda dengan allowedTools dan disallowedTools
  • Referensi TypeScript SDK: Referensi API lengkap termasuk opsi konfigurasi MCP
  • Referensi Python SDK: Referensi API lengkap termasuk opsi konfigurasi MCP
  • Direktori server MCP: Jelajahi server MCP yang tersedia untuk database, API, dan lainnya