Tutorial Lengkap 2026: Membangun MCP Server TypeScript untuk AI Agent yang Aman dan Production-Ready

Durasi baca: ±15 menit
Level: Intermediate (pemula yang serius tetap bisa ikut)
Stack: Node.js, TypeScript, Model Context Protocol (MCP)

1) Introduction — What and Why

Kalau kamu aktif ngikutin tren developer beberapa bulan terakhir, kamu pasti lihat satu pola: hampir semua tim sedang bereksperimen dengan AI agent. Dari GitHub Trending, repo bertema agent dan tool integration naik cepat. Di ekosistem MCP sendiri, adopsi makin luas karena banyak client (IDE, chatbot, app internal) butuh cara standar untuk “nyambung” ke data dan tools eksternal.

Masalah klasiknya: sebelum ada standar, tiap integrasi AI cenderung ad-hoc. Hari ini kamu bikin endpoint custom buat baca database, besok bikin adapter lagi buat file system, minggu depan nambah API eksternal dengan format berbeda. Akhirnya:

integrasi berantakan,
sulit dipelihara,
dan paling bahaya: security policy tidak konsisten.

Di sinilah Model Context Protocol (MCP) relevan. Anggap saja seperti “USB-C untuk AI app”: satu protokol standar untuk expose tools, resources, dan prompts ke model/agent.

Di tutorial ini, kita akan fokus bikin MCP Server berbasis TypeScript yang:

runnable lokal,
punya error handling yang proper,
aman dari input yang aneh,
gampang dikembangkan ke use case nyata.

Kita akan bangun contoh server “Task Helper” dengan dua tool utama:

create_task: buat task baru,
list_tasks: lihat daftar task dengan filter.

Walau sederhana, pola arsitekturnya sama seperti yang dipakai di sistem production.

2) Prerequisites — Sebelum Mulai

Siapkan dulu ini:

Node.js 20+
npm / pnpm (contoh pakai npm)
TypeScript basic (interface, async/await)
Paham HTTP & JSON dasar
IDE favorit (VS Code recommended)

Install global opsional:

npm i -g tsx

Kenapa tsx? Karena kamu bisa jalanin file TypeScript langsung tanpa setup build pipeline berat di tahap awal.

3) Core Concepts — Fundamental dengan Analogi

Supaya kebayang, mari pakai analogi restoran 🍜

MCP Client = pelayan yang menerima pesanan user/model.
MCP Server = dapur yang punya kemampuan spesifik.
Tool = menu aksi (contoh: “buat task”, “ambil data”).
Resource = bahan/data referensi (dokumen, file, dsb).
Transport = jalur komunikasi (stdio atau HTTP streamable).

Konsep penting yang wajib kamu pegang

Tool contract harus jelas
Input schema dan output schema harus konsisten. Ini mencegah model menebak-nebak format.
Server jangan terlalu permisif
Jangan expose tool yang bisa ngapa-ngapain tanpa guardrail.
Validasi input adalah keharusan
Jangan percaya input dari model 100%. Model bisa halusinasi parameter.
Error harus terstruktur
Error message yang bagus mempercepat debugging dan membuat agent lebih stabil.
Security by design
Mulai dari principle of least privilege: tool hanya punya akses minimum yang dibutuhkan.

4) Architecture / Diagram

Kita pakai arsitektur sederhana seperti ini:

+-------------------+        MCP Transport        +-------------------------+
| MCP Client/Agent  |  <----------------------->  | MCP Server (TypeScript) |
| (IDE / Chat App)  |                             |                         |
+-------------------+                             |  +-------------------+  |
                                                  |  | Tool Registry     |  |
                                                  |  | - create_task     |  |
                                                  |  | - list_tasks      |  |
                                                  |  +-------------------+  |
                                                  |            |            |
                                                  |  +-------------------+  |
                                                  |  | Service Layer     |  |
                                                  |  | validation + biz  |  |
                                                  |  +-------------------+  |
                                                  |            |            |
                                                  |  +-------------------+  |
                                                  |  | In-memory store   |  |
                                                  |  | (demo; can swap)  |  |
                                                  |  +-------------------+  |
                                                  +-------------------------+

Flow request:

Agent manggil tool create_task.
MCP server validasi input.
Service layer proses logika bisnis.
Hasil dikembalikan dalam format yang konsisten.

5) Step-by-Step Implementation (Runnable)

5.1 Inisialisasi proyek

mkdir mcp-task-server
cd mcp-task-server
npm init -y
npm i @modelcontextprotocol/server zod
npm i -D typescript tsx @types/node
npx tsc --init

Update package.json script:

{
  "scripts": {
    "dev": "tsx src/index.ts"
  }
}

5.2 Buat file `src/index.ts`

Kode di bawah ini lengkap dan runnable untuk demo lokal.

import { z } from "zod";

type TaskStatus = "todo" | "in_progress" | "done";

interface Task {
  id: string;
  title: string;
  description?: string;
  status: TaskStatus;
  createdAt: string;
}

// In-memory store untuk demo. Di production bisa diganti PostgreSQL/Redis.
const tasks: Task[] = [];

// Utility: generate id sederhana
function generateId(): string {
  return `task_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
}

// Schema validasi input
const createTaskSchema = z.object({
  title: z.string().min(3, "title minimal 3 karakter").max(120),
  description: z.string().max(1000).optional(),
  status: z.enum(["todo", "in_progress", "done"]).default("todo")
});

const listTasksSchema = z.object({
  status: z.enum(["todo", "in_progress", "done"]).optional(),
  limit: z.number().int().min(1).max(100).default(20)
});

// Bentuk response yang konsisten
function ok(data: unknown) {
  return {
    success: true,
    data,
    timestamp: new Date().toISOString()
  };
}

function fail(message: string, detail?: unknown) {
  return {
    success: false,
    error: {
      message,
      detail
    },
    timestamp: new Date().toISOString()
  };
}

// Simulasi handler tool MCP (portable untuk berbagai transport)
async function createTaskTool(input: unknown) {
  try {
    const parsed = createTaskSchema.parse(input);

    const newTask: Task = {
      id: generateId(),
      title: parsed.title,
      description: parsed.description,
      status: parsed.status,
      createdAt: new Date().toISOString()
    };

    tasks.push(newTask);

    return ok({
      message: "Task berhasil dibuat",
      task: newTask
    });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return fail("Validasi input gagal", error.flatten());
    }

    return fail("Terjadi error saat membuat task", String(error));
  }
}

async function listTasksTool(input: unknown) {
  try {
    const parsed = listTasksSchema.parse(input);

    let result = [...tasks];
    if (parsed.status) {
      result = result.filter((t) => t.status === parsed.status);
    }

    result = result.slice(0, parsed.limit);

    return ok({
      count: result.length,
      items: result
    });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return fail("Validasi input gagal", error.flatten());
    }

    return fail("Terjadi error saat mengambil task", String(error));
  }
}

// Demo runner agar file bisa dijalankan langsung
async function main() {
  console.log("MCP Task Server Demo starting...
");

  // 1) create task valid
  const create1 = await createTaskTool({
    title: "Belajar MCP TypeScript",
    description: "Implement tool create_task & list_tasks",
    status: "todo"
  });
  console.log("[create_task #1]", JSON.stringify(create1, null, 2));

  // 2) create task invalid (contoh error handling)
  const create2 = await createTaskTool({ title: "Hi" });
  console.log("
[create_task #2 - invalid]", JSON.stringify(create2, null, 2));

  // 3) list tasks
  const list = await listTasksTool({ status: "todo", limit: 10 });
  console.log("
[list_tasks]", JSON.stringify(list, null, 2));

  console.log("
Demo selesai. Integrasikan handler ini ke MCP transport (stdio/http) sesuai client kamu.");
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});

Jalankan:

npm run dev

Kalau output menampilkan response success + validasi error, berarti fondasi kamu sudah benar.

5.3 Integrasi ke MCP Transport nyata

Di implementasi production, handler createTaskTool dan listTasksTool didaftarkan ke server MCP sesuai SDK/transport yang kamu pilih (stdio atau Streamable HTTP). Prinsipnya tetap sama:

daftar nama tool,
definisikan schema input,
return output terstruktur,
audit logging di setiap invocation.

6) Best Practices — Tips dari Lapangan

Schema-first development
Definisikan schema input/output dulu, baru logic. Ini menurunkan bug integrasi drastis.
Idempotency untuk operasi kritikal
Tool seperti create_payment atau submit_order wajib punya idempotency key.
Audit log per tool call
Simpan: siapa memanggil, kapan, parameter penting, hasil, latency.
Timeout + retry policy
Jangan biarkan tool call menggantung. Terapkan timeout eksplisit.
Least privilege access
Jika tool hanya perlu read data, jangan kasih write permission.
Rate limiting
Lindungi server dari loop invocation berlebihan dari agent.
Versioning contract
Kalau ubah schema, gunakan versioning (v1, v2) agar client lama tidak rusak.

7) Common Mistakes — Yang Sering Bikin Sistem Rapuh

Mistake #1: Menganggap output model selalu valid

Model bisa kirim field yang typo atau missing. Solusi: validasi ketat + default aman.

Mistake #2: Error message terlalu generik

Internal Error tanpa detail membuat debugging lama. Solusi: error code + detail terstruktur (tanpa bocorin rahasia).

Mistake #3: Tool “super admin”

Satu tool bisa akses semua hal adalah anti-pattern keamanan. Solusi: pecah tools jadi granular.

Mistake #4: Tidak membatasi ukuran input

Payload panjang bisa bikin crash/memory spike. Solusi: set max length di schema.

Mistake #5: Langsung production tanpa observability

Tanpa metrics/logs, kamu buta saat ada incident. Solusi: pasang tracing dari awal.

8) Advanced Tips — Kalau Mau Naik Level

A) Tambah persistence nyata

Ganti in-memory store ke PostgreSQL:

tabel tasks(id, title, description, status, created_at)
index di status dan created_at

B) Tambah auth layer

Untuk remote MCP server, gunakan OAuth dan token scoping. Pastikan tool sensitif butuh scope khusus.

C) Guard against prompt injection side-effects

Walau injection terjadi di level konten model, dampaknya bisa sampai tool call. Mitigasi:

whitelist domain/tool,
require confirmation untuk aksi destruktif,
sanitize dan batasi parameter.

D) Multi-tenant design

Jika dipakai banyak tim/tenant:

setiap request wajib bawa tenantId,
query selalu di-scope tenant,
audit log dipisah per tenant.

E) Uji dengan contract testing

Buat test yang memastikan schema tool tidak berubah diam-diam. Ini penting untuk kestabilan agent.

9) Summary & Next Steps

Kita sudah bahas end-to-end cara membangun MCP server TypeScript yang rapi:

paham konsep MCP (tool, resource, transport),
desain arsitektur minimal tapi scalable,
implementasi runnable dengan validasi + error handling,
best practices dan jebakan umum,
langkah lanjut ke production.

Next step yang saya sarankan minggu ini:

Integrasikan contoh tool ke transport MCP nyata (stdio/http).
Tambahkan database (PostgreSQL).
Tambahkan auth + audit log.
Buat 3 test contract untuk input/output tool.
Deploy staging dan uji dengan 1 client agent nyata.

Kalau 5 langkah ini selesai, kamu sudah punya fondasi kuat untuk membangun AI workflow yang lebih serius (misalnya customer support assistant, internal ops assistant, atau engineering copilot).

10) References

Berikut referensi utama untuk pendalaman:

Model Context Protocol — Introduction
https://modelcontextprotocol.io/introduction
MCP TypeScript SDK (official)
https://github.com/modelcontextprotocol/typescript-sdk
MCP Reference Servers (official examples)
https://github.com/modelcontextprotocol/servers
OpenAI Docs — Building MCP servers for apps/API integrations
https://developers.openai.com/api/docs/mcp/
VS Code Docs — Add and manage MCP servers
https://code.visualstudio.com/docs/copilot/customization/mcp-servers

Catatan Riset Tren (April 2026)

GitHub Trending menunjukkan lonjakan repositori bertema AI agent tooling dan on-device/LLM integration.
Ekosistem MCP makin matang dengan SDK, reference servers, dan adopsi lintas tool developer.
Topik integrasi aman (auth, sandboxing, least privilege) semakin sering dibahas karena adopsi agent menuju production.

Kalau kamu ingin seri lanjutan, topik paling relevan berikutnya adalah: "MCP Client orchestration + observability untuk multi-tool agent".

Tutorial Lengkap 2026: Membangun MCP Server TypeScript untuk AI Agent yang Aman dan Production-Ready

Tutorial Lengkap 2026: Membangun MCP Server TypeScript untuk AI Agent yang Aman dan Production-Ready

1) Introduction — What and Why

2) Prerequisites — Sebelum Mulai

3) Core Concepts — Fundamental dengan Analogi

Konsep penting yang wajib kamu pegang

4) Architecture / Diagram

5) Step-by-Step Implementation (Runnable)

5.1 Inisialisasi proyek

5.2 Buat file src/index.ts

5.3 Integrasi ke MCP Transport nyata

6) Best Practices — Tips dari Lapangan

7) Common Mistakes — Yang Sering Bikin Sistem Rapuh

Mistake #1: Menganggap output model selalu valid

Mistake #2: Error message terlalu generik

Mistake #3: Tool “super admin”

Mistake #4: Tidak membatasi ukuran input

Mistake #5: Langsung production tanpa observability

8) Advanced Tips — Kalau Mau Naik Level

A) Tambah persistence nyata

B) Tambah auth layer

C) Guard against prompt injection side-effects

D) Multi-tenant design

E) Uji dengan contract testing

9) Summary & Next Steps

10) References

Catatan Riset Tren (April 2026)

5.2 Buat file `src/index.ts`