Tutorial MCP Server TypeScript dan PostgreSQL untuk AI Agent

Model Context Protocol (MCP) menjadi standar komunikasi antara AI agent dan sumber data eksternal sejak diperkenalkan oleh Anthropic. Bayangkan Claude bisa membaca skema database, menjalankan query read-only, dan memberikan insight langsung dari data PostgreSQL milikmu. Di tutorial ini, kita akan membangun MCP server sederhana menggunakan TypeScript yang menghubungkan Claude Desktop ke database PostgreSQL lokal.

MCP server berfungsi sebagai jembatan antara LLM dan dunia eksternal. Berbeda dengan sekadar prompt engineering, MCP memungkinkan AI agent mengakses resource dan tool secara terstruktur. Kamu bisa menemukan dokumentasi lengkap MCP di modelcontextprotocol.io atau melihat koleksi server referensi di github.com/modelcontextprotocol/servers.

Apa yang Akan Dibangun

Kita akan membuat satu MCP server yang menyediakan dua kemampuan utama:

Resource: Daftar tabel dan kolom dari database PostgreSQL yang bisa dibaca Claude sebagai konteks.
Tool: Fungsi execute_query untuk menjalankan query SELECT read-only.

Server ini menggunakan transport stdio sehingga kompatibel langsung dengan Claude Desktop tanpa perlu setup HTTP server.

Prasyarat

Sebelum mulai, pastikan environment kamu sudah siap:

Node.js 18 atau lebih baru
PostgreSQL yang berjalan secara lokal
Claude Desktop sudah terpasang
Database contoh dengan beberapa tabel untuk testing

Langkah 1: Inisialisasi Proyek TypeScript

Buat folder baru dan inisialisasi proyek Node.js. Pilihlah TypeScript sebagai bahasa utama karena SDK MCP TypeScript sudah sangat matang dan didokumentasikan dengan baik.

mkdir mcp-postgres-server
cd mcp-postgres-server
npm init -y
npx tsc --init

Tambahkan konfigurasi tsconfig.json yang sesuai untuk target ES2022 agar fitur modern seperti top-level await berfungsi dengan baik.

Langkah 2: Instalasi Dependensi

Instal SDK MCP resmi dari Anthropic bersama driver PostgreSQL. Kita menggunakan pg karena stabil dan banyak digunakan di ekosistem Node.js.

npm install @modelcontextprotocol/sdk pg
npm install -D @types/pg typescript

Jika kamu menggunakan package manager lain seperti pnpm atau bun, sesuaikan saja perintahnya. Yang penting, versi @modelcontextprotocol/sdk yang digunakan minimal 1.0 agar kompatibel dengan spesifikasi terbaru.

Langkah 3: Membuat Koneksi PostgreSQL

Buat file db.ts yang menangani koneksi dan helper query. Pastikan koneksi menggunakan user dengan privilege read-only jika server akan dijalankan di environment shared.

import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL ||
    'postgresql://user:pass@localhost:5432/mydb',
});

export async function query(sql: string) {
  const client = await pool.connect();
  try {
    const result = await client.query(sql);
    return result.rows;
  } finally {
    client.release();
  }
}

Gunakan connection pooling agar performa tetap optimal saat Claude melakukan banyak request dalam satu sesi.

Langkah 4: Implementasi Resource dan Tool

Buat file index.ts sebagai entry point MCP server. Di sini kita mendefinisikan resource schema://tables yang mereturn daftar tabel, dan tool execute_query yang menjalankan SELECT statement.

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from
  '@modelcontextprotocol/sdk/server/stdio.js';
import { query } from './db.js';

const server = new Server(
  { name: 'postgres-mcp', version: '1.0.0' },
  {
    capabilities: {
      resources: {},
      tools: {},
    },
  }
);

server.setRequestHandler('resources/list', async () => {
  return {
    resources: [
      {
        uri: 'schema://tables',
        name: 'Database Tables',
        mimeType: 'application/json',
      },
    ],
  };
});

server.setRequestHandler('resources/read', async (req) => {
  if (req.params.uri === 'schema://tables') {
    const rows = await query(
      "SELECT table_name FROM information_schema.tables " +
      "WHERE table_schema = 'public'"
    );
    return {
      contents: [
        {
          uri: req.params.uri,
          mimeType: 'application/json',
          text: JSON.stringify(rows, null, 2),
        },
      ],
    };
  }
  throw new Error('Resource not found');
});

server.setRequestHandler('tools/list', async () => {
  return {
    tools: [
      {
        name: 'execute_query',
        description: 'Execute a read-only SQL query',
        inputSchema: {
          type: 'object',
          properties: {
            sql: { type: 'string', description: 'SELECT query to run' },
          },
          required: ['sql'],
        },
      },
    ],
  };
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'execute_query') {
    const sql = req.params.arguments?.sql as string;
    if (!sql.trim().toLowerCase().startsWith('select')) {
      throw new Error('Only SELECT queries are allowed');
    }
    const rows = await query(sql);
    return {
      content: [
        { type: 'text', text: JSON.stringify(rows, null, 2) },
      ],
    };
  }
  throw new Error('Tool not found');
});

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

Perhatikan validasi query di handler tools/call. Kita secara eksplisit menolak query selain SELECT untuk mencegah manipulasi data secara tidak sengaja.

Langkah 5: Build dan Konfigurasi Claude Desktop

Compile TypeScript ke JavaScript agar bisa dijalankan langsung oleh Node.js. Tambahkan script build di package.json.

npx tsc

Setelah itu, tambahkan konfigurasi server ke file claude_desktop_config.json sesuai sistem operasi kamu. Untuk macOS, file ini berada di ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "postgres-local": {
      "command": "node",
      "args": [
        "/path/to/mcp-postgres-server/dist/index.js"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Restart Claude Desktop agar perubahan konfigurasi terdeteksi. Sebaiknya gunakan path absolut untuk file JavaScript agar tidak ada masalah working directory.

Langkah 6: Testing dengan Claude

Buka Claude Desktop dan mulai percakapan baru. Tanyakan: "What tables are available in my database?" atau "Show me the top 5 users ordered by created_at."

Claude akan secara otomatis mendeteksi resource dan tool dari MCP server yang sudah dikonfigurasi. Ikuti alur persetujuan jika Claude meminta konfirmasi sebelum menjalankan tool. Untuk tips debugging jika server tidak muncul, baca panduan MCP Inspector.

Kesimpulan

Membangun MCP server memang memerlukan setup awal, tapi manfaat jangka panjangnya sangat besar. AI agent tidak lagi terbatas pada knowledge cutoff dan bisa mengakses data real-time dari sistem produksi. Dengan approach read-only dan validasi query ketat, kamu bisa memberikan akses database ke Claude tanpa mengorbankan keamanan.

Jika ingin melanjutkan, coba integrasikan MCP server ini dengan CI/CD pipeline atau deploy sebagai remote server menggunakan transport SSE. Referensi lengkap tersedia di dokumentasi resmi MCP.

Tutorial Membangun MCP Server dengan TypeScript: Hubungkan Claude ke PostgreSQL