Langsung ke konten utama
RekayasaMar 28, 2026

Membangun Server MCP Pertama Anda: Panduan Praktis untuk Developer

OS
Open Soft Team

Engineering Team

Apa Itu Model Context Protocol (MCP)?

Model Context Protocol (MCP) adalah standar terbuka yang dibuat oleh Anthropic yang mendefinisikan cara aplikasi AI berkomunikasi dengan sumber data dan alat eksternal. Bayangkan MCP sebagai USB-C untuk integrasi AI: seperti USB-C yang menyediakan satu konektor universal untuk pengisian daya, transfer data, dan output tampilan, MCP menyediakan satu protokol universal untuk menghubungkan model AI ke database, API, sistem file, dan layanan lainnya. MCP menghilangkan kebutuhan akan integrasi khusus antara setiap aplikasi AI dan setiap alat.

Pada tahun 2026, MCP telah menjadi standar dominan untuk komunikasi AI-alat. Gartner memprediksi bahwa 40% aplikasi enterprise akan menyertakan AI agent pada akhir 2026, dan MCP adalah protokol yang membuatnya praktis dalam skala besar. Sebelum MCP, menghubungkan model AI ke N alat memerlukan N integrasi khusus. Dengan M aplikasi AI dan N alat, Anda memerlukan M x N adapter integrasi. MCP mengurangi ini menjadi M + N: setiap aplikasi AI mengimplementasikan satu MCP client, setiap alat mengimplementasikan satu MCP server.

Arsitektur MCP: Host, Client, Server, dan Transport

Memahami arsitektur MCP sangat penting sebelum menulis kode apa pun. Protokol ini mendefinisikan empat peran kunci:

KomponenPeranContoh
HostAplikasi AI yang berinteraksi dengan pengguna akhirClaude Desktop, Cursor, VS Code Copilot
ClientHandler protokol MCP di dalam hostDibangun ke dalam aplikasi host
ServerMenyediakan tools, resources, dan prompts melalui MCPServer kustom Anda (yang akan kita bangun)
TransportLapisan komunikasi antara client dan serverstdio, HTTP+SSE, Streamable HTTP

Alur komunikasi bekerja seperti ini:

  1. Host memulai dan menginisialisasi MCP client untuk setiap server yang dikonfigurasi.
  2. Client terhubung ke server melalui transport (stdio untuk lokal, HTTP untuk remote).
  3. Client mengirim permintaan initialize, menegosiasikan versi protokol dan kemampuan.
  4. Server merespons dengan tools, resources, dan prompts yang tersedia.
  5. Ketika model AI membutuhkan data atau tindakan eksternal, client memanggil metode server yang sesuai.
  6. Server mengeksekusi operasi dan mengembalikan hasil melalui pesan JSON-RPC 2.0.

Tools vs Resources vs Prompts

MCP server dapat menyediakan tiga jenis kemampuan:

  • Tools adalah fungsi yang dapat dipanggil oleh model AI. Mereka menerima input terstruktur dan mengembalikan output terstruktur. Contoh: query_database(sql: string) atau send_email(to: string, subject: string, body: string).
  • Resources adalah data yang dapat dibaca oleh model AI. Mereka diidentifikasi oleh URI dan mengembalikan konten. Contoh: file:///path/to/document.md atau postgres://localhost/mydb/users.
  • Prompts adalah template prompt yang dapat digunakan kembali yang disediakan server. Mereka membantu menstandarkan cara AI berinteraksi dengan domain server. Contoh: template summarize_ticket untuk Jira MCP server.

Langkah demi Langkah: Membangun MCP Server di TypeScript

Mari kita bangun MCP server praktis yang menyediakan tool untuk melakukan query ke database SQLite. Ini adalah kasus penggunaan umum: memberikan model AI akses baca-saja yang aman ke data aplikasi Anda.

Langkah 1: Inisialisasi Proyek

mkdir mcp-sqlite-server && cd mcp-sqlite-server
npm init -y
npm install @modelcontextprotocol/sdk better-sqlite3
npm install -D typescript @types/node @types/better-sqlite3
npx tsc --init

Konfigurasi tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

Langkah 2: Implementasi Server

Buat src/index.ts:

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

const db = new Database(process.env.DB_PATH || "./data.db", {
  readonly: true,
});

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

server.tool(
  "query",
  "Eksekusi query SQL read-only terhadap database SQLite",
  {
    sql: z.string().describe("Query SQL SELECT yang akan dieksekusi"),
  },
  async ({ sql }) => {
    const normalized = sql.trim().toUpperCase();
    if (!normalized.startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Hanya query SELECT yang diperbolehkan." }],
        isError: true,
      };
    }
    try {
      const rows = db.prepare(sql).all();
      return {
        content: [{ type: "text", text: JSON.stringify(rows, null, 2) }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error query: ${(error as Error).message}` }],
        isError: true,
      };
    }
  }
);

server.tool(
  "list_tables",
  "Daftar semua tabel dalam database beserta skemanya",
  {},
  async () => {
    const tables = db
      .prepare(
        `SELECT name, sql FROM sqlite_master
         WHERE type='table' AND name NOT LIKE 'sqlite_%'
         ORDER BY name`
      )
      .all();
    return {
      content: [{ type: "text", text: JSON.stringify(tables, null, 2) }],
    };
  }
);

Langkah 3: Build dan Uji Secara Lokal

npx tsc
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

Anda akan melihat respons JSON-RPC dengan kemampuan server.

Langkah 4: Bangun Server yang Sama di Python

Untuk developer Python, berikut implementasi setara menggunakan SDK Python MCP resmi:

import sqlite3
import json
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("sqlite-query")
DB_PATH = "data.db"

@mcp.tool()
def query(sql: str) -> str:
    """Eksekusi query SQL read-only terhadap database SQLite."""
    normalized = sql.strip().upper()
    if not normalized.startswith("SELECT"):
        raise ValueError("Hanya query SELECT yang diperbolehkan.")
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    try:
        cursor = conn.execute(sql)
        rows = [dict(row) for row in cursor.fetchall()]
        return json.dumps(rows, indent=2, default=str)
    finally:
        conn.close()

@mcp.tool()
def list_tables() -> str:
    """Daftar semua tabel dalam database beserta skemanya."""
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    try:
        cursor = conn.execute(
            "SELECT name, sql FROM sqlite_master "
            "WHERE type='table' AND name NOT LIKE 'sqlite_%'"
        )
        tables = [dict(row) for row in cursor.fetchall()]
        return json.dumps(tables, indent=2)
    finally:
        conn.close()

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

Menghubungkan ke Claude Desktop

Claude Desktop mendukung MCP server secara native. Untuk menghubungkan server Anda, edit file konfigurasi Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sqlite-query": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "DB_PATH": "/absolute/path/to/your/data.db"
      }
    }
  }
}

Restart Claude Desktop. Anda akan melihat ikon palu di antarmuka chat yang menunjukkan tool MCP yang tersedia. Sekarang Anda dapat bertanya kepada Claude seperti “Tabel apa saja yang ada di database?” atau “Tampilkan 10 pengguna teratas berdasarkan tanggal pendaftaran” dan Claude akan menggunakan MCP server Anda untuk melakukan query database secara langsung.

Menghubungkan ke Cursor

Cursor juga mendukung MCP server. Tambahkan konfigurasi ke .cursor/mcp.json di root proyek Anda:

{
  "mcpServers": {
    "sqlite-query": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "DB_PATH": "./data.db"
      }
    }
  }
}

Setelah menyimpan, restart Cursor. Tool MCP akan muncul di panel asisten AI dan dapat dipanggil selama sesi pembuatan kode dan debugging.

Pengujian dan Debugging MCP Server Anda

Menggunakan MCP Inspector

MCP Inspector adalah tool debugging resmi. Ini menyediakan antarmuka web untuk berinteraksi dengan server Anda:

npx @modelcontextprotocol/inspector node dist/index.js

Ini membuka antarmuka browser di http://localhost:5173 di mana Anda dapat:

  • Melihat semua tools, resources, dan prompts yang terdaftar
  • Memanggil tools dengan input kustom dan memeriksa respons
  • Memantau aliran pesan JSON-RPC secara real time
  • Menguji penanganan error dengan mengirim permintaan yang salah format

Masalah Debugging Umum

MasalahPenyebabSolusi
Server tidak muncul di Claude DesktopPath konfigurasi atau error sintaks JSONValidasi JSON, periksa path absolut
Error “Tool not found”Server tidak mendaftarkan tools sebelum connectDaftarkan tools sebelum memanggil server.connect()
Timeout pada panggilan toolOperasi berjalan lama tanpa progresTambahkan notifikasi progres via server.sendProgress()
Output stderr merusak protokolConsole.log menulis ke stdout (transport stdio)Gunakan console.error() untuk logging dengan stdio
Koneksi terputus setelah idleTimeout transportImplementasikan heartbeat atau gunakan transport HTTP

Praktik Terbaik untuk Produksi

  1. Validasi input: Selalu validasi dan sanitasi input tool. Gunakan skema Zod (TypeScript) atau model Pydantic (Python) untuk pemeriksaan tipe yang ketat.

  2. Read-only secara default: Mulai dengan akses read-only. Hanya tambahkan kemampuan tulis ketika benar-benar diperlukan, dan selalu minta konfirmasi untuk operasi destruktif.

  3. Penanganan error: Kembalikan pesan error terstruktur dengan isError: true. Jangan pernah mengekspos stack trace internal atau string koneksi database.

  4. Logging: Log semua pemanggilan tool dengan timestamp, input, dan durasi eksekusi. Gunakan stderr untuk log (bukan stdout) saat menggunakan transport stdio.

  5. Rate limiting: Implementasikan batas rate per-tool untuk mencegah loop AI yang tidak terkendali dari membanjiri layanan backend Anda.

  6. Timeout: Tetapkan timeout eksekusi pada semua handler tool. Model AI mungkin memanggil tool yang memicu query mahal — lindungi infrastruktur Anda.

  7. Pemisahan environment: Gunakan variabel environment untuk semua konfigurasi. Jangan pernah hardcode URL database, API key, atau path file.

  8. Versioning: Ikuti semantic versioning untuk MCP server Anda. Handshake initialize mencakup negosiasi versi — perubahan breaking memerlukan bump versi major.

FAQ

T: Apa perbedaan antara MCP dan function calling? J: Function calling (digunakan oleh OpenAI, Anthropic, dan lainnya) mendefinisikan tools secara inline dalam setiap permintaan API. MCP mengeksternalisasi definisi tool ke server mandiri yang dapat ditemukan dan digunakan oleh host yang kompatibel dengan MCP. Function calling bersifat per-permintaan; MCP adalah protokol persisten dengan sesi stateful.

T: Bisakah saya menggunakan MCP dengan model selain Claude? J: Ya. MCP adalah protokol terbuka. OpenAI, Google DeepMind, dan Microsoft telah mengadopsi dukungan MCP di platform mereka sejak awal 2026. Aplikasi AI apa pun yang mengimplementasikan MCP client dapat terhubung ke MCP server mana pun.

T: Apakah MCP hanya untuk tool lokal? J: Tidak. Meskipun transport stdio dirancang untuk server lokal, transport HTTP+SSE dan Streamable HTTP mendukung MCP server remote. Anda dapat men-deploy MCP server sebagai layanan cloud yang dapat diakses melalui jaringan.

T: Bagaimana MCP menangani autentikasi? J: Protokol ini mendukung OAuth 2.0 untuk server remote. Server stdio lokal mewarisi konteks keamanan dari proses host. Untuk deployment enterprise, MCP gateway dapat memusatkan autentikasi dan otorisasi.

T: Bahasa apa yang dapat digunakan untuk membangun MCP server? J: SDK resmi tersedia untuk TypeScript, Python, Java, Kotlin, C#, dan Swift. SDK komunitas mencakup Rust, Go, Ruby, dan PHP. Protokolnya agnostik bahasa — bahasa apa pun yang dapat membaca/menulis JSON-RPC melalui stdio atau HTTP dapat mengimplementasikan MCP server.

T: Bagaimana cara memperbarui MCP server tanpa me-restart host? J: MCP mendukung notifikasi perubahan kemampuan. Ketika tools server Anda berubah, server dapat mengirim pesan notifications/tools/list_changed, yang mendorong client untuk mengambil ulang daftar tool. Untuk server stdio, host biasanya perlu restart. Server HTTP dapat diperbarui tanpa restart host.

Tag
AITypeScript