Membangun MCP Server di TypeScript: Panduan

Model Context Protocol, atau MCP, adalah standar terbuka untuk menghubungkan klien AI ke tool dan data eksternal melalui satu antarmuka konsisten. Alih-alih menulis integrasi khusus untuk tiap asisten, Anda membangun satu MCP server dan klien kompatibel mana pun, termasuk Claude Code, bisa memakainya. Ia sering digambarkan sebagai port USB-C untuk aplikasi AI.

Panduan ini membangun server kecil di TypeScript dari nol. Kita akan merangka proyek dengan SDK resmi, mengekspos tool bertipe, menghubungkan server ke klien, dan membahas apa yang berubah ketika Anda beranjak dari prototipe lokal ke sesuatu yang diandalkan orang lain.

Apa itu MCP server dan mengapa membangunnya

Sebuah MCP server adalah program yang mengekspos kapabilitas ke klien AI melalui protokol terstruktur yang dibangun di atas JSON-RPC. Klien dan server bertukar pesan dalam bentuk yang terdefinisi, sehingga model bisa menemukan apa yang ditawarkan server dan memanggilnya tanpa lem khusus apa pun di sisi klien.

Anda akan membangunnya ketika Anda ingin sebuah asisten menjangkau sesuatu yang tak bisa dilihatnya sendiri:

• Sebuah API atau database internal yang berada di balik autentikasi Anda sendiri.
• Sebuah tool yang melakukan aksi nyata, seperti membuat tiket atau menjalankan laporan.
• Sebuah sumber konteks langsung, seperti dokumentasi atau konfigurasi, yang perlu dibaca model sesuai permintaan.

Rangka servernya

Mulailah proyek Node dan pasang dua paket: MCP SDK resmi untuk TypeScript dan pustaka schema seperti Zod untuk memvalidasi masukan. SDK memberi Anda objek server dan seperangkat transport; Zod memungkinkan Anda menjelaskan argumen tiap tool dalam bentuk yang diubah SDK menjadi schema yang bisa dibaca klien.

Sebuah server minimal yang mendaftarkan satu tool dan berbicara melalui standard input dan output terlihat seperti ini:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "weather",
  version: "1.0.0",
});

server.tool(
  "get_forecast",
  "Get a short weather forecast for a city",
  { city: z.string().describe("City to look up") },
  async ({ city }) => ({
    content: [
      { type: "text", text: "Forecast for " + city + ": sunny, 27C" },
    ],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Tambahkan tool bertipe

Sebuah tool adalah aksi yang bisa dipilih model untuk dipanggil. Masing-masing butuh empat hal, dan membuatnya benar adalah yang membuat tool tersebut dapat dipakai alih-alih menjadi sumber kebingungan.

• Sebuah name yang jelas dan unik yang dipakai model untuk merujuk tool tersebut.
• Sebuah description singkat yang memberi tahu model persis kapan tool tersebut harus dipakai.
• Sebuah schema masukan, didefinisikan dengan Zod, sehingga argumen divalidasi sebelum handler Anda berjalan.
• Sebuah handler yang mengerjakan tugasnya dan mengembalikan konten yang dirender klien kembali ke model.

Hubungkan ke klien

Dengan server terbangun, daftarkan ke sebuah klien. Di Claude Code Anda menambahkan server dengan perintah claude mcp add, mengarahkannya ke perintah yang meluncurkan server Anda; klien lain menyimpan informasi yang sama dalam berkas konfigurasi. Begitu terdaftar, klien menjalankan server dan mendaftar tool-nya secara otomatis.

Sebelum menyambungkannya ke asisten sungguhan, uji server secara terpisah dengan MCP Inspector, sebuah tool mandiri yang terhubung ke server Anda dan memungkinkan Anda mendaftar serta memanggil kapabilitasnya secara manual. Menangkap schema yang rusak di Inspector jauh lebih murah daripada men-debug-nya lewat antarmuka chat.

Dari prototipe lokal ke produksi

Sebuah server stdio di laptop Anda adalah awal, bukan akhir. Beranjak ke sesuatu yang dibagikan atau jarak jauh membawa beberapa keputusan yang bisa diabaikan versi lokal.

• Beralih dari stdio ke transport Streamable HTTP ketika server harus dijangkau melalui jaringan alih-alih diluncurkan secara lokal.
• Tambahkan autentikasi dan otorisasi, karena server jarak jauh terpapar dengan cara yang tak pernah dialami proses anak lokal.
• Tangani error dan logging secara sengaja, agar tool yang gagal mengembalikan pesan jelas alih-alih menggantung diam.

Membangun MCP server di TypeScript sebagian besar soal tiga langkah: rangka dengan SDK resmi, jelaskan tiap tool dengan schema masukan yang ketat, dan pilih transport yang cocok dengan tempat server berjalan. Mulai lokal lewat stdio, validasi tiap masukan, dan Anda punya jembatan yang bisa dipakai ulang oleh klien MCP mana pun.