Tutorial Membuat MCP Server dengan Python: Hubungkan Internal Tools ke Claude Code dan Cursor

Model Context Protocol (MCP) telah menjadi standar de facto untuk menghubungkan AI agent dengan tools eksternal. Diciptakan oleh Anthropic, MCP memungkinkan Claude Code, Cursor, dan IDE lainnya berkomunikasi langsung dengan database, API internal, atau bahkan file system lokal kamu. Artikel ini akan membahas cara membangun MCP server sendiri menggunakan Python, lengkap dengan contoh implementasi yang bisa langsung dicoba.

MCP bekerja dengan pola client-server sederhana. Client (seperti Claude Code) mengirim request dalam format JSON-RPC, lalu server mengeksekusi tool yang diminta dan mengembalikan hasilnya. Keunggulan utama dari pendekatan ini adalah developers tidak perlu lagi copy-paste konteks manual setiap kali berinteraksi dengan AI. Semuanya terjadi secara otomatis dan real-time.

Prasyarat dan Setup Environment

Sebelum mulai coding, pastikan environment kamu sudah siap. Kamu memerlukan Python 3.10 atau lebih baru, serta pip untuk menginstal dependency. MCP SDK resmi dari Anthropic tersedia sebagai package Python bernama mcp.

Buat direktori baru untuk project ini dan inisialisasi virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install mcp httpx

Kita juga akan menggunakan httpx untuk melakukan HTTP request ke API eksternal. Pastikan kamu sudah familiar dengan konsep async/await di Python, karena MCP SDK sepenuhnya berbasis asyncio.

Langkah 1: Inisialisasi Server dengan FastMCP

Anthropic menyediakan class FastMCP yang sangat mempermudah pembuatan server. Class ini menangani routing JSON-RPC, manajemen lifecycle, dan registrasi tool secara otomatis. Buat file server.py dan tulis kode berikut:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("internal-tools-server")

@mcp.tool()
async def fetch_user_data(user_id: str) -> str:
    """Ambil data pengguna dari internal API berdasarkan user_id."""
    import httpx
    async with httpx.AsyncClient() as client:
        resp = await client.get(f"https://api.internal.company.com/users/{user_id}")
        return resp.text

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

Decorator @mcp.tool() akan secara otomatis mendaftarkan fungsi sebagai tool yang tersedia untuk client. Docstring dari fungsi tersebut juga akan digunakan sebagai deskripsi tool, jadi pastikan kamu menulisnya dengan jelas.

Langkah 2: Menambahkan Tool dengan Parameter Kompleks

Tool yang hanya menerima string terlalu sederhana untuk kebutuhan production. MCP mendukung parameter bertipe kompleks seperti list, dict, dan enum. Berikut contoh tool untuk query database internal:

from typing import Literal

@mcp.tool()
async def query_database(
    table: Literal["users", "orders", "products"],
    limit: int = 10
) -> str:
    """Query database internal dengan batas jumlah baris."""
    import sqlite3
    conn = sqlite3.connect("/path/to/internal.db")
    cursor = conn.cursor()
    cursor.execute(f"SELECT * FROM {table} LIMIT ?", (limit,))
    rows = cursor.fetchall()
    conn.close()
    return str(rows)

Perhatikan penggunaan Literal dari modul typing. Tipe ini memberi tahu client bahwa parameter table hanya boleh diisi dengan tiga nilai tertentu. Claude Code akan menggunakan informasi ini untuk memvalidasi input sebelum mengirim request ke server.

Langkah 3: Konfigurasi Claude Code untuk Menggunakan Server

Setelah server siap, kamu perlu mendaftarkannya ke Claude Code. Buat atau edit file konfigurasi di ~/.claude-code/config.json:

{
  "mcpServers": {
    "internal-tools": {
      "command": "python3",
      "args": ["/path/to/server.py"]
    }
  }
}

Jika kamu menggunakan Cursor, navigasi ke Settings > MCP Servers dan tambahkan konfigurasi serupa. Cursor mendukung format yang identik dengan Claude Code, sehingga migration antar IDE sangat mudah.

Setelah konfigurasi disimpan, restart Claude Code. Kamu akan melihat tool baru muncul di panel Available Tools. Coba prompt sederhana seperti: "Cari data user dengan ID 12345 menggunakan internal API." Claude akan secara otomatis memanggil fetch_user_data dan menampilkan hasilnya.

Langkah 4: Debugging dan Error Handling

Production server harus memiliki error handling yang robust. MCP SDK menyediakan exception class McpError untuk mengembalikan error terstruktur ke client. Modifikasi tool kamu untuk menangani edge cases:

from mcp import McpError

@mcp.tool()
async def safe_api_call(endpoint: str) -> str:
    """Panggil API internal dengan retry logic."""
    import httpx
    try:
        async with httpx.AsyncClient(timeout=10.0) as client:
            resp = await client.get(f"https://api.internal.company.com{endpoint}")
            resp.raise_for_status()
            return resp.text
    except httpx.HTTPStatusError as e:
        raise McpError(f"HTTP error {e.response.status_code}: {e.response.text}")
    except Exception as e:
        raise McpError(f"Unexpected error: {str(e)}")

Untuk debugging, jalankan server secara manual di terminal terpisah sebelum menghubungkannya ke Claude Code. Gunakan flag --verbose jika tersedia, atau tambahkan print() statement untuk melacak alur request dan response.

Langkah 5: Deployment dan Best Practices

Di lingkungan production, MCP server sebaiknya dijalankan sebagai systemd service atau container Docker. Berikut contoh unit file untuk systemd:

[Unit]
Description=MCP Internal Tools Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/mcp-server
ExecStart=/opt/mcp-server/venv/bin/python server.py
Restart=on-failure

[Install]
WantedBy=multi-user.target

Jika kamu men-deploy ke mesin remote, pertimbangkan untuk menambahkan layer autentikasi. MCP specification saat ini tidak memiliki autentikasi bawaan, sehingga kamu perlu mengimplementasikannya sendiri menggunakan middleware atau reverse proxy seperti Nginx dengan basic auth.

Selalu dokumentasikan setiap tool yang kamu daftarkan. Tim engineering lainnya akan menggunakan deskripsi tersebut untuk memahami kapabilitas server. Semakin spesifik deskripsi tool kamu, semakin akurat AI dalam memilih tool yang tepat untuk setiap tugas.

Kesimpulan

Membangun MCP server dengan Python adalah investasi yang sangat berharga untuk meningkatkan produktivitas tim engineering. Dengan menghubungkan internal tools langsung ke AI agent, kamu mengurangi waktu konteks switching dan meminimalkan kesalahan manual. Protocol ini terus berkembang, dan dukungan dari berbagai IDE menandakan adopsi yang semakin luas.

Untuk dokumentasi resmi dan contoh lebih lanjut, kunjungi Model Context Protocol Documentation. Repository contoh kode juga tersedia di GitHub MCP Python SDK.