Tutorial Membangun MCP Server dengan TypeScript: Hubungkan API Internal ke Claude Code

Model Context Protocol (MCP) telah menjadi standar de facto untuk menghubungkan AI agent dengan data dan tools eksternal. Dibangun oleh Anthropic, protokol ini memungkinkan LLM seperti Claude Code mengakses database, API internal, atau file system secara aman melalui interface yang terstandardisasi. Dalam tutorial ini, kita akan membangun MCP server sederhana dengan TypeScript yang menghubungkan API internal perusahaan ke Claude Code.

Mengapa MCP Penting untuk Developer

Sebelum MCP, integrasi AI dengan sistem internal memerlukan custom script yang rapuh dan sulit dikelola. MCP menyediakan arsitektur client-server yang bersih: Claude Code bertindak sebagai client yang memanggil tools yang diekspos oleh server kita. Setiap tool memiliki schema JSON yang jelas, sehingga LLM tahu persis kapan dan bagaimana menggunakannya. Pendekatan ini mengurangi hallucination dan meningkatkan keandalan AI dalam konteks bisnis.

Perbedaan utama MCP dengan pendekatan function calling tradisional terletak pada standardisasi. Client seperti Claude Code, Cursor, atau IDE lain yang mendukung MCP dapat langsung menggunakan server yang kita bangun tanpa modifikasi. Ini berarti satu kali investasi development bisa digunakan di banyak platform AI sekaligus.

Prasyarat dan Setup Proyek

Pastikan Node.js versi 18 atau lebih baru sudah terinstall di sistem kamu. Kita akan menggunakan TypeScript dan SDK official dari Anthropic untuk mempercepat development. Buat direktori baru dan inisialisasi proyek dengan perintah berikut:

mkdir mcp-internal-api
cd mcp-internal-api
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx zod-to-json-schema

Buat file tsconfig.json dengan konfigurasi standar untuk Node.js. SDK MCP menggunakan Zod untuk validasi schema, jadi kita install sekalian untuk type safety yang maksimal. Package zod-to-json-schema diperlukan untuk mengkonversi schema Zod ke format JSON Schema yang dipahami oleh MCP client.

Langkah 1: Definisikan Schema Tool dengan Zod

Setiap tool dalam MCP harus memiliki nama, deskripsi, dan schema parameter. Deskripsi sangat penting karena LLM menggunakannya untuk memutuskan tool mana yang akan dipanggil. Mari definisikan tool untuk mengambil data pengguna dari API internal:

import { z } from "zod";

const GetUserSchema = z.object({
  userId: z.string().describe("ID unik pengguna dalam sistem internal"),
  includeInactive: z.boolean().optional().describe("Sertakan pengguna non-aktif")
});

type GetUserInput = z.infer<typeof GetUserSchema>;

Perhatikan penggunaan .describe() pada setiap field. Claude Code membaca deskripsi ini untuk memahami konteks bisnis dan memastikan parameter yang dikirim sesuai ekspektasi. Semakin spesifik deskripsimu, semakin akurat LLM dalam memilih dan mengisi parameter.

Langkah 2: Implementasikan Handler Tool

Handler adalah fungsi yang dieksekusi ketika Claude Code memanggil tool. Di sini kita melakukan fetch ke API internal dan mengembalikan data dalam format yang diharapkan MCP:

async function handleGetUser(args: GetUserInput) {
  const url = new URL(`${process.env.INTERNAL_API_URL}/users/${args.userId}`);
  if (args.includeInactive) {
    url.searchParams.set("includeInactive", "true");
  }
  
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.API_TOKEN}` }
  });
  
  if (!response.ok) {
    throw new Error(`API gagal dengan status ${response.status}: ${response.statusText}`);
  }
  
  const data = await response.json();
  return {
    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }]
  };
}

Selalu kembalikan error yang informatif. Claude Code akan membaca pesan error dan sering kali dapat memperbaiki parameter atau menyarankan solusi kepada pengguna. Hindari mengembalikan stack trace mentah ke client karena bisa membocorkan informasi sensitif sistem internal.

Langkah 3: Bangun dan Jalankan MCP Server

Gunakan Server class dari SDK untuk meregistrasikan tools dan menjalankan transport layer. Kita menggunakan stdio transport yang paling umum untuk integrasi dengan Claude Code desktop:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  ListToolsRequestSchema,
  CallToolRequestSchema
} from "@modelcontextprotocol/sdk/types.js";
import { zodToJsonSchema } from "zod-to-json-schema";

const server = new Server(
  { name: "internal-api-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "get_user",
    description: "Ambil detail pengguna dari sistem internal HR",
    inputSchema: zodToJsonSchema(GetUserSchema)
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_user") {
    const args = GetUserSchema.parse(request.params.arguments);
    return handleGetUser(args);
  }
  throw new Error("Tool tidak ditemukan");
});

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

Pastikan untuk menangkap error di level paling atas dengan try-catch sehingga server tidak crash ketika API internal sedang down atau ada input yang tidak valid.

Langkah 4: Konfigurasi Claude Code Desktop

Setelah server berjalan, tambahkan konfigurasi ke file claude_desktop_config.json. Lokasi file bervariasi menurut sistem operasi. Pada macOS, file ini berada di ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "internal-api": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-internal-api/src/index.ts"],
      "env": {
        "INTERNAL_API_URL": "https://api.perusahaan.internal",
        "API_TOKEN": "token_rahasia_anda"
      }
    }
  }
}

Restart Claude Code setelah mengubah konfigurasi. Kamu akan melihat tools baru muncul di panel capabilities. Coba tanyakan "Ambil data pengguna dengan ID 12345" dan Claude akan secara otomatis memanggil tool yang baru saja kita buat. Jika server berjalan dengan benar, kamu akan melihat response dari API internal muncul dalam chat.

Langkah 5: Debugging dan Best Practices Keamanan

Saat development, gunakan environment variable MCP_DEBUG=true untuk melihat log detail setiap request dan response. Selalu validasi input dengan Zod sebelum mengirim ke API internal untuk mencegah injection attack. Pertimbangkan untuk menambahkan rate limiting di handler jika API internal memiliki batasan quota.

Untuk deployment di production, compile TypeScript ke JavaScript dengan tsc dan gunakan PM2 atau systemd untuk menjalankan server sebagai background service. Jangan hardcode credential dalam source code. Gunakan secret manager atau environment variable yang aman.

Dokumentasi lengkap MCP tersedia di modelcontextprotocol.io dan SDK TypeScript dapat diakses di GitHub resmi Anthropic. Komunitas MCP juga aktif di Discord Anthropic untuk diskusi teknis dan troubleshooting.

Dengan MCP, integrasi AI ke stack teknologi internal menjadi lebih terstruktur dan maintainable. Protokol ini membuka peluang untuk membangun agent-agent pintar yang benar-benar memahami konteks bisnis perusahaan kamu.