Model Context Protocol

Ada dua hal yang sebaiknya sudah akrab bagimu, karena keduanya persis yang lewat di kabel MCP.

• JSON-RPC 2.0 adalah format sederhana untuk memanggil fungsi lewat pesan JSON. Sebuah request punya id, method, dan params. Response membawa result atau error dengan id yang sama, sehingga kamu tahu jawaban mana untuk permintaan mana. Notification tak punya id dan tak dijawab. MCP menambah satu aturan: id tak boleh null.
• JSON Schema adalah cara baku menuliskan bentuk data: type, properties, required. Untuk inputSchema dan outputSchema tool, MCP memakai dialek 2020-12 secara bawaan.

Semuanya akan lebih mudah bila kamu sudah membaca topik Tool use, atau pernah memanggil LLM lewat API dengan function calling. MCP adalah cara baku menyediakan fungsi-fungsi itu dari luar aplikasi.

Cara terbaik memahami arsitektur MCP adalah menggambarnya sendiri. Lihat diagram ini, lalu gambar ulang dengan tanganmu sampai kamu bisa menjelaskannya tanpa melihat:

Saat menggambar, pastikan tiga hal ini terlihat:

1. Satu host membuat satu client untuk setiap server.
2. Server lokal (stdio) biasanya melayani satu client, sedangkan server jarak jauh (Streamable HTTP) melayani banyak client.
3. Riwayat percakapan tinggal di host. Server hanya menerima yang perlu, dan tak bisa melihat server lain.

Bedakan juga dua lapisnya: data (JSON-RPC dan primitif) dan transport (stdio atau HTTP, pembingkaian, otorisasi).

Ketiga primitif server tampak mirip, tetapi dikendalikan pihak yang berbeda, dan perbedaan itu menentukan cara kamu merancangnya.

• Tools dikendalikan model. Model memilih memanggilnya, lalu host meminta persetujuan.
• Resources dikendalikan aplikasi. Host yang memutuskan data mana masuk konteks, misalnya lewat pemilih berkas. Setiap resource dikenali lewat URI seperti file:///project/src/main.rs.
• Prompts dikendalikan pengguna, dan biasanya muncul sebagai perintah garis miring.

Semua primitif ditemukan saat aplikasi berjalan lewat metode list-nya (tools/list, resources/list, prompts/list), bukan dari konfigurasi tetap, sehingga daftarnya boleh berubah. Server yang menyatakan listChanged memberi tahu perubahan itu kepada client yang membuka aliran subscriptions/listen.

Di sisi client, hanya Elicitation yang dianjurkan untuk implementasi baru: server meminta masukan dari pengguna, misalnya konfirmasi sebelum sebuah tindakan. Sampling dan Roots, juga utilitas Logging, kini deprecated.

Latihan: pilih satu sistem yang kamu kenal, misalnya aplikasi catatan. Tulis dua tool, satu resource, dan satu prompt untuknya, lalu tandai siapa yang seharusnya memutuskan masing-masing dipakai.

Karena tak ada lagi jabat tangan, setiap permintaan harus memperkenalkan dirinya sendiri. Perkenalan itu ditaruh di _meta:

Permintaan yang tak membawa kunci wajib ditolak dengan -32602 (di HTTP: status 400). Bila server butuh kapabilitas yang tak dinyatakan client, ia menjawab -32021 sambil menyebut kapabilitas yang kurang. Server pun sebaiknya memperkenalkan diri di _meta setiap hasil (io.modelcontextprotocol/serverInfo).

server/discover wajib ada di setiap server, tetapi client tak wajib memanggilnya. Jawabannya memuat supportedVersions, capabilities, serta petunjuk cache ttlMs dan cacheScope.

Saatnya membangun. Tutorial resmi Build an MCP server mengajakmu membuat server cuaca dengan dua tool, get_alerts dan get_forecast. Kerangkanya dengan SDK Python seperti ini:

from mcp.server import MCPServer

mcp = MCPServer("weather")

@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    ...

if __name__ == "__main__":
    mcp.run(transport="stdio")

Yang menarik, petunjuk tipe dan docstring di atas adalah skemanya: dari state: str, SDK membuat inputSchema sendiri. Di TypeScript, padanannya McpServer dari paket @modelcontextprotocol/server, dengan registerTool dan skema Zod.

Pesan stdio dipisahkan baris baru dan tak boleh memuat baris baru di dalamnya. Host menghentikan servermu dengan menutup stdin, jadi pastikan servermu keluar dengan rapi saat stdin habis.

Begitu server berjalan, kamu pasti ingin melihat apa yang sebenarnya terjadi. Untuk itulah ada MCP Inspector, alat pengembang rujukan: satu paket dengan tiga antarmuka, yaitu web, CLI, dan TUI (antarmuka di terminal). Ia butuh Node 22.19.0 atau lebih baru.

# antarmuka web, tersambung ke server stdio hasil build TypeScript
npx @modelcontextprotocol/inspector node build/index.js

# CLI: daftar tool lalu keluar — cocok untuk skrip dan CI
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# antarmuka terminal
npx @modelcontextprotocol/inspector --tui node build/index.js

Untuk server Python dari SDK resmi, uv run mcp dev server.py langsung membukanya di Inspector.

Kirim tools/list, lalu tools/call, dan baca pesan mentahnya di panel pemantau. Kamu akan melihat bahwa setiap permintaan membawa _meta-nya sendiri dan setiap hasil membawa resultType. Melihat JSON yang benar-benar lewat adalah cara tercepat memahami apa yang selama ini disembunyikan SDK darimu.

Model hanya melihat tiga hal dari tool-mu: nama, deskripsi, dan skema. Ketiganya adalah wajah tool-mu, jadi rancang dengan cermat.

• Nama: 1–128 karakter; huruf, angka, _, -, dan .; peka huruf besar-kecil; unik di dalam server.
• Deskripsi: apa yang dilakukan, dan kapan dipakai.
• inputSchema: JSON Schema. Untuk tool tanpa parameter, anjurannya {"type": "object", "additionalProperties": false}.
• outputSchema (opsional): bila ada, server wajib mengembalikan structuredContent yang sesuai, dan sebaiknya juga salinannya sebagai teks.

Galat juga perlu dirancang. MCP membedakan dua jenis, masing-masing dengan jalannya sendiri:

{
  "resultType": "complete",
  "content": [
    {
      "type": "text",
      "text": "Invalid departure date: must be in the future."
    }
  ],
  "isError": true
}

Kenapa dibedakan? Galat eksekusi diteruskan ke model supaya ia bisa memperbaiki panggilannya sendiri, misalnya memilih tanggal lain. Galat protokol jarang bisa diperbaiki model. Satu kiat kecil: kembalikan tools/list dalam urutan yang tetap, supaya client bisa menyimpannya dan prompt cache LLM lebih sering kena.

Server yang hanya diuji di Inspector belum benar-benar hidup. Tutorial resmi memakai Claude for Desktop sebagai host. Daftarkan servermu di claude_desktop_config.json (di Windows: $env:AppData\Claude\claude_desktop_config.json), di bawah kunci mcpServers:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/JALUR/ABSOLUT/weather", "run", "weather.py"]
    }
  }
}

Mulai ulang host, minta sesuatu yang membutuhkan tool-mu, lalu amati kapan model memilih memanggilnya.

Spesifikasi menganjurkan agar selalu ada manusia yang bisa menolak pemanggilan tool. Karena itu aplikasi sebaiknya:

• menampilkan tool mana yang terpapar ke model,
• menandai dengan jelas saat tool dipanggil,
• meminta konfirmasi untuk operasi yang berdampak.

Cari di host-mu di mana ketiganya terlihat. Bagian ini tak bisa dipaksakan oleh protokol; ia tanggung jawab host.

Tanpa sesi, bagaimana server mengingat keranjang belanja yang baru dibuat? Di MCP, koneksi, bahkan proses stdio sekalipun, bukan percakapan. Ada dua pola yang menggantikan sesi.

1. Pegangan eksplisit. Mirip nomor tiket penitipan barang: tool pembuat mengembalikan ID, dan tool lain menerimanya sebagai argumen biasa.

// → tools/call
{ "name": "create_basket", "arguments": {} }
// → tools/call berikutnya
{
  "name": "add_item",
  "arguments": { "basket_id": "bsk_a1b2c3", "sku": "..." }
}

Buat pegangan acak yang tak bisa ditebak (misalnya UUIDv4), tulis umurnya di deskripsi tool, dan kembalikan galat eksekusi yang jelas untuk pegangan kedaluwarsa, supaya model tahu ia perlu membuat yang baru.

2. Multi Round-Trip Requests (MRTR). Kadang server butuh masukan pengguna di tengah tools/call, resources/read, atau prompts/get. Alih-alih bertanya langsung, ia membalas InputRequiredResult, lalu client mengulang permintaannya dengan jawaban pengguna:

requestState adalah teks buram milik server, dan client wajib mengembalikannya apa adanya. Permintaan ulang wajib memakai id JSON-RPC yang baru.

Server MCP menjalankan kode atas permintaan model, jadi keamanannya tak boleh jadi urusan belakangan. Spesifikasi mewajibkan (MUST) empat hal di sisi server: validasi semua masukan tool, kendalikan akses, batasi laju pemanggilan, dan bersihkan keluaran. Panduan keamanan resmi lalu menyebut empat jebakan:

• Token passthrough. Server hanya boleh menerima token yang diterbitkan untuknya (periksa audiensnya) dan tak boleh meneruskan token itu ke API hilir. Butuh API lain? Minta token tersendiri untuk API itu.
• Pembajakan pegangan. Memegang ID bukan bukti identitas. Ikat pegangan ke pengguna terautentikasi di sisi server, mis. kunci user_id:handle dengan user_id dari token yang terverifikasi, bukan dari client.
• Server lokal yang berbahaya. Server lokal berjalan dengan hak akses client. Host yang menawarkan pemasangan sekali klik wajib menampilkan perintah lengkapnya dan meminta persetujuan, dan sebaiknya menjalankannya di kotak pasir.
• Deskripsi yang menipu. Anotasi dan deskripsi tool dari server yang tak tepercaya dianggap tak tepercaya.

Di sisi client, spesifikasi menganjurkan (SHOULD): tampilkan masukan tool sebelum dikirim (mencegah kebocoran data), validasi hasil sebelum diteruskan ke LLM, pasang batas waktu, dan catat pemakaian tool untuk audit.

Server stdio hanya bisa dipakai di mesin yang sama. Supaya bisa dipakai lewat jaringan, servermu perlu Streamable HTTP: setiap pesan dari client adalah POST baru ke satu endpoint MCP, dan server menjawab dengan satu objek JSON atau aliran SSE (Server-Sent Events). Header wajibnya:

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_weather

Nilai header harus sama dengan isi badan. Bila berbeda, server menolak dengan 400 dan -32020 (HeaderMismatch), supaya penyeimbang beban yang membaca header dan server yang membaca badan tak pernah berselisih.

Tiga aturan keamanan transport:

• validasi header Origin di setiap koneksi (403 bila tak sah) untuk menangkal DNS rebinding;
• saat berjalan lokal, dengarkan hanya di 127.0.0.1, bukan 0.0.0.0;
• autentikasi semua koneksi.

Otorisasinya OAuth 2.1. Server wajib menerbitkan Protected Resource Metadata (RFC 9728), client wajib menyebut server tujuan lewat parameter resource (RFC 8707), dan pendaftaran client dianjurkan lewat Client ID Metadata Documents; Dynamic Client Registration kini deprecated. Server stdio tak memakai kerangka ini: kredensialnya diambil dari lingkungan proses.

Daftar tool bisa bertambah dan isi berkas bisa berubah. Bagaimana client tahu? Kini semuanya tiba lewat satu permintaan berumur panjang:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscriptions/listen",
  "params": {
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["file:///project/config.json"]
    }
  }
}

(_meta wajib tetap ada; di sini disingkat.) Server lebih dulu mengirim notifications/subscriptions/acknowledged, berisi jenis notifikasi yang benar-benar ia layani. Sesudah itu datang notifikasi bertanda io.modelcontextprotocol/subscriptionId, yang nilainya id permintaan listen tadi. Notifikasi milik satu permintaan tertentu, seperti notifications/progress, tetap lewat aliran jawaban permintaan itu.

Cache melengkapinya. Hasil server/discover, tools/list, prompts/list, resources/list, resources/templates/list, dan resources/read wajib membawa ttlMs (berapa milidetik hasil boleh dianggap segar) dan cacheScope (public atau private). TTL hanya petunjuk kesegaran, bukan janji bahwa data tak akan berubah.