Blog

Cara Cepat Membuat Server MCP untuk Kode Claude

Audrey Lopez

Audrey Lopez

12 June 2025

Cara Cepat Membuat Server MCP untuk Kode Claude

Model Context Protocol (MCP) merevolusi cara asisten AI berinteraksi dengan alat eksternal dan sumber data. Anggap MCP sebagai port USB-C universal untuk aplikasi AI—ini menyediakan cara standar untuk menghubungkan Kode Claude ke hampir semua sumber data, API, atau alat yang dapat Anda bayangkan. Panduan komprehensif ini akan memandu Anda membangun server MCP Anda sendiri dari awal, memungkinkan Kode Claude mengakses fungsionalitas kustom yang memperluas kemampuannya jauh melampaui fitur bawaannya.

Baik Anda ingin mengintegrasikan database, API, sistem file, atau membuat alat yang sepenuhnya kustom, MCP menyediakan fondasi untuk ekstensibilitas tanpa batas. Di akhir tutorial ini, Anda akan memiliki server MCP yang berfungsi dan memahami cara mengembangkannya untuk kasus penggunaan apa pun.

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda agar dapat bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Apa itu MCP Server dan Mengapa Semua Orang Membicarakannya

Apa yang Membuat MCP Berbeda

MCP (Model Context Protocol) adalah protokol terbuka yang dikembangkan oleh Anthropic yang memungkinkan model AI berkomunikasi dengan server eksternal melalui antarmuka standar. Tidak seperti integrasi API tradisional di mana Anda mengkodekan titik akhir tertentu secara permanen, MCP menyediakan cara terstruktur bagi asisten AI untuk menemukan, memahami, dan menggunakan alat eksternal secara dinamis.

Keunggulan MCP terletak pada kemampuannya untuk ditemukan (discoverability). Ketika Kode Claude terhubung ke server MCP Anda, ia secara otomatis mempelajari alat apa yang tersedia, cara menggunakannya, dan parameter apa yang diterima. Ini berarti Anda dapat menambahkan fungsionalitas baru tanpa memperbarui Kode Claude itu sendiri.

Mendalami Arsitektur MCP

Protokol ini mengikuti arsitektur klien-server dengan peran yang jelas:

Penjelasan Alur Komunikasi

Ketika Kode Claude perlu menggunakan alat eksternal, inilah yang terjadi:

  1. Fase Penemuan: Kode Claude meminta server Anda untuk alat yang tersedia
  2. Validasi Skema: Server Anda merespons dengan definisi alat dan skema input
  3. Pemilihan Alat: Kode Claude memilih alat yang sesuai berdasarkan permintaan pengguna
  4. Fase Eksekusi: Kode Claude mengirim panggilan alat dengan parameter yang divalidasi
  5. Pemrosesan Hasil: Server Anda memproses permintaan dan mengembalikan hasil terstruktur

Alur ini memastikan keamanan tipe, penanganan kesalahan yang tepat, dan perilaku yang konsisten di seluruh integrasi MCP.

Prasyarat dan Pengaturan Lingkungan

Analisis Persyaratan Sistem

Sebelum membangun server MCP Anda, Anda perlu memahami lingkungan pengembangan Anda dan memilih alat yang tepat. Server MCP dapat dibangun dalam berbagai bahasa, tetapi Python dan TypeScript adalah yang paling umum didukung dengan banyak alat.

Untuk Pengembangan Python:

Untuk Pengembangan TypeScript/JavaScript:

Dependensi Inti:

Persiapan Lingkungan Langkah demi Langkah

1. Instal Claude Code CLI

Claude Code CLI adalah alat utama Anda untuk mengelola server MCP. Instal secara global untuk memastikan akses dari direktori mana pun:

# Instal Claude Code secara global
npm install -g @anthropic-ai/claude-code

Mengapa instalasi global penting: Instalasi global memastikan perintah claude tersedia di seluruh sistem, mencegah masalah terkait path saat mendaftarkan server MCP dari direktori yang berbeda.

2. Verifikasi Instalasi

Periksa apakah Claude Code terinstal dengan benar dan dapat diakses:

# Verifikasi instalasi dan periksa versi
claude --version

# Periksa perintah yang tersedia
claude --help

3. Pengaturan Izin Kritis Pertama Kali

Langkah ini benar-benar penting dan sering terabaikan:

# Jalankan pengaturan awal dengan melewati izin
claude --dangerously-skip-permissions

Apa yang dilakukan perintah ini:

Mengapa ini diperlukan: Tanpa langkah ini, server MCP tidak dapat membangun koneksi aman dengan Kode Claude, yang menyebabkan kegagalan otentikasi dan waktu habis koneksi.

Pertimbangan keamanan: Flag --dangerously-skip-permissions aman untuk lingkungan pengembangan tetapi melewati prompt keamanan normal. Di lingkungan produksi, tinjau setiap permintaan izin dengan cermat.

Konfigurasi Kritis: Memahami Lingkup MCP

Mengapa Lingkup Konfigurasi Penting

Salah satu kesalahan paling umum saat membangun server MCP adalah manajemen lingkup konfigurasi yang tidak tepat. Memahami lingkup sangat penting karena menentukan di mana dan kapan server MCP Anda tersedia untuk Kode Claude. Banyak pengembang menghabiskan berjam-jam men-debug kesalahan "server tidak ditemukan" yang berasal dari kesalahan konfigurasi lingkup.

Kode Claude menggunakan sistem konfigurasi hierarkis yang dirancang untuk memberikan fleksibilitas sambil menjaga keamanan. Setiap lingkup melayani tujuan tertentu dan memiliki kasus penggunaan yang berbeda.

Penjelasan Hierarki Lingkup Konfigurasi

1. Lingkup Proyek (.mcp.json) - Prioritas Tertinggi

Lokasi: Direktori root proyek dalam file .mcp.json

Tujuan: Server MCP khusus proyek yang seharusnya hanya tersedia saat bekerja di proyek spesifik tersebut

Kasus penggunaan: Koneksi database khusus proyek, linter khusus proyek, atau alat build kustom

Kapan lingkup proyek sesuai:

2. Lingkup Pengguna (-scope user) - Konfigurasi Global

Lokasi: Konfigurasi direktori home pengguna

Tujuan: Server MCP tersedia secara global di semua proyek dan direktori

Kasus penggunaan: Alat serbaguna seperti API cuaca, alat kalkulator, atau utilitas sistem

Mengapa lingkup pengguna biasanya lebih disukai:

3. Lingkup Lokal (default) - Khusus Direktori

Lokasi: Konteks direktori kerja saat ini

Tujuan: Pengaturan server MCP yang cepat dan sementara

Batasan: Hanya berfungsi saat Anda menjalankan Kode Claude dari direktori spesifik tersebut

Kesalahan Konfigurasi Umum

❌ Pendekatan yang salah (Lingkup Lokal - fungsionalitas terbatas):

claude mcp add my-server python3 /path/to/server.py

Masalah: Server ini hanya berfungsi saat Anda berada di direktori yang sama persis di mana Anda mendaftarkannya.

✅ Pendekatan yang benar (Lingkup Pengguna - akses global):

claude mcp add --scope user my-server python3 /path/to/server.py

Manfaat: Server ini berfungsi dari direktori mana pun di sistem Anda.

Perencanaan Direktori Strategis

Struktur Direktori yang Direkomendasikan

Buat struktur direktori yang terorganisir dengan baik untuk pemeliharaan jangka panjang:

# Buat lokasi penyimpanan permanen
mkdir -p ~/.claude-mcp-servers/

# Atur berdasarkan fungsionalitas
mkdir -p ~/.claude-mcp-servers/apis/
mkdir -p ~/.claude-mcp-servers/utilities/
mkdir -p ~/.claude-mcp-servers/development/

Manfaat Struktur yang Terorganisir

Pemeliharaan: Mudah menemukan dan memperbarui server nanti

Keamanan: Pemisahan yang jelas antara berbagai jenis alat

Cadangan: Mudah mencadangkan semua server MCP dengan mencadangkan satu direktori

Berbagi: Mudah berbagi konfigurasi server dengan anggota tim

Panduan Pemecahan Masalah Lingkup

Mendiagnosis Masalah Lingkup

Jika server MCP Anda tidak muncul, ikuti urutan diagnostik ini:

  1. Periksa konfigurasi lingkup saat ini:
claude mcp list
  1. Verifikasi Anda tidak berada di direktori dengan lingkup proyek yang bertentangan:
ls .mcp.json
  1. Uji dari direktori yang berbeda:
cd ~ && claude mcp list
cd /tmp && claude mcp list

Memperbaiki Masalah Lingkup

Masalah: Server hanya berfungsi di satu direktori

Solusi: Hapus konfigurasi lokal dan tambahkan kembali dengan lingkup pengguna

# Hapus konfigurasi lokal yang bermasalah
claude mcp remove my-server

# Tambahkan kembali dengan lingkup pengguna global
claude mcp add --scope user my-server python3 /path/to/server.py

Membangun Server MCP Pertama Anda

Memahami Proses Pengembangan

Membangun server MCP melibatkan pemahaman protokol MCP dan persyaratan spesifik kasus penggunaan Anda. Kita akan mulai dengan server "Hello World" dasar untuk memahami fundamental, lalu membangun di atas fondasi tersebut.

Proses pengembangan mengikuti fase-fase ini:

  1. Pengaturan Struktur Server: Membuat struktur file dasar dan titik masuk
  2. Implementasi Protokol: Mengimplementasikan metode MCP yang diperlukan
  3. Definisi Alat: Mendefinisikan alat apa yang disediakan server Anda
  4. Registrasi & Pengujian: Menambahkan server ke Kode Claude dan memverifikasi fungsionalitas
  5. Peningkatan & Produksi: Menambahkan fungsionalitas nyata dan penanganan kesalahan

Langkah 1: Fondasi dan Struktur Proyek

Membuat Lingkungan Pengembangan

Pertama, bangun lingkungan pengembangan yang tepat untuk server MCP Anda:

# Navigasi ke direktori server MCP Anda
cd ~/.claude-mcp-servers/

# Buat proyek server baru
mkdir my-first-server
cd my-first-server

# Inisialisasi struktur proyek
touch server.py
touch requirements.txt
touch .env

Mengapa Struktur Ini Penting

Pengembangan yang Terorganisir: Menjaga setiap server dalam direktori sendiri mencegah konflik dan memudahkan pemeliharaan.

Isolasi Dependensi: Setiap server dapat memiliki persyaratannya sendiri tanpa memengaruhi yang lain.

Manajemen Konfigurasi: File lingkungan memungkinkan konfigurasi aman tanpa mengkodekan nilai secara permanen.

Memahami Persyaratan Server MCP

Setiap server MCP harus mengimplementasikan tiga metode inti JSON-RPC:

  1. initialize: Membangun koneksi dan mendeklarasikan kemampuan server
  2. tools/list: Mengembalikan alat yang tersedia dan skemanya
  3. tools/call: Mengeksekusi panggilan alat spesifik dengan parameter yang disediakan

Langkah 2: Mengimplementasikan Kerangka Kerja Server Inti

Buat file bernama server.py dengan templat server MCP dasar:

#!/usr/bin/env python3
"""
Custom MCP Server for Claude Code Integration
"""

import json
import sys
import os
from typing import Dict, Any, Optional

# Ensure unbuffered output for proper MCP communication
sys.stdout = os.fdopen(sys.stdout.fileno(), 'w', 1)
sys.stderr = os.fdopen(sys.stderr.fileno(), 'w', 1)

def send_response(response: Dict[str, Any]):
    """Send a JSON-RPC response to Claude Code"""
    print(json.dumps(response), flush=True)

def handle_initialize(request_id: Any) -> Dict[str, Any]:
    """Handle MCP initialization handshake"""
    return {
        "jsonrpc": "2.0",
        "id": request_id,
        "result": {
            "protocolVersion": "2024-11-05",
            "capabilities": {
                "tools": {}
            },
            "serverInfo": {
                "name": "my-custom-server",
                "version": "1.0.0"
            }
        }
    }

def handle_tools_list(request_id: Any) -> Dict[str, Any]:
    """List available tools for Claude Code"""
    tools = [
        {
            "name": "hello_world",
            "description": "A simple demonstration tool",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Name to greet"
                    }
                },
                "required": ["name"]
            }
        }
    ]

    return {
        "jsonrpc": "2.0",
        "id": request_id,
        "result": {
            "tools": tools
        }
    }

def handle_tool_call(request_id: Any, params: Dict[str, Any]) -> Dict[str, Any]:
    """Execute tool calls from Claude Code"""
    tool_name = params.get("name")
    arguments = params.get("arguments", {})

    try:
        if tool_name == "hello_world":
            name = arguments.get("name", "World")
            result = f"Hello, {name}! Your MCP server is working perfectly."
        else:
            raise ValueError(f"Unknown tool: {tool_name}")

        return {
            "jsonrpc": "2.0",
            "id": request_id,
            "result": {
                "content": [
                    {
                        "type": "text",
                        "text": result
                    }
                ]
            }
        }
    except Exception as e:
        return {
            "jsonrpc": "2.0",
            "id": request_id,
            "error": {
                "code": -32603,
                "message": str(e)
            }
        }

def main():
    """Main server loop handling JSON-RPC communication"""
    while True:
        try:
            line = sys.stdin.readline()
            if not line:
                break

            request = json.loads(line.strip())
            method = request.get("method")
            request_id = request.get("id")
            params = request.get("params", {})

            if method == "initialize":
                response = handle_initialize(request_id)
            elif method == "tools/list":
                response = handle_tools_list(request_id)
            elif method == "tools/call":
                response = handle_tool_call(request_id, params)
            else:
                response = {
                    "jsonrpc": "2.0",
                    "id": request_id,
                    "error": {
                        "code": -32601,
                        "message": f"Method not found: {method}"
                    }
                }

            send_response(response)

        except json.JSONDecodeError:
            continue
        except EOFError:
            break
        except Exception as e:
            if 'request_id' in locals():
                send_response({
                    "jsonrpc": "2.0",
                    "id": request_id,
                    "error": {
                        "code": -32603,
                        "message": f"Internal error: {str(e)}"
                    }
                })

if __name__ == "__main__":
    main()

Penjelasan Arsitektur Kode

Pengaturan Input/Output: Beberapa baris pertama mengonfigurasi I/O tanpa buffer, yang sangat penting untuk komunikasi MCP. Output yang dibuffer dapat menyebabkan penundaan pengiriman pesan yang merusak protokol.

Penanganan JSON-RPC: Loop utama membaca permintaan JSON-RPC dari stdin dan menulis respons ke stdout. Ini mengikuti spesifikasi MCP untuk komunikasi server lokal.

Strategi Penanganan Kesalahan: Kode mengimplementasikan beberapa lapisan penanganan kesalahan:

Kepatuhan Protokol: Setiap respons mencakup bidang jsonrpc: "2.0" yang diperlukan dan ID permintaan untuk korelasi yang tepat.

Langkah 3: Persiapan dan Pengujian Server

Membuat Server Dapat Dieksekusi

# Jadikan server dapat dieksekusi
chmod +x server.py

Mengapa izin eksekusi penting: Server MCP diluncurkan sebagai subprocess oleh Kode Claude. Tanpa izin eksekusi, peluncuran akan gagal dengan kesalahan izin yang tidak jelas.

Pengujian Protokol Manual

Sebelum mendaftar dengan Kode Claude, uji implementasi protokol server:

# Uji jabat tangan inisialisasi
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 server.py

Apa yang diharapkan: Anda akan melihat respons JSON yang berisi versi protokol dan kemampuan. Jika Anda melihat pesan kesalahan atau tidak ada output, periksa instalasi Python dan sintaks skrip Anda.

Langkah Validasi

Lakukan pemeriksaan validasi ini sebelum melanjutkan:

  1. Pemeriksaan Sintaks: python3 -m py_compile server.py
  2. Uji Impor: python3 -c "import json, sys, os"
  3. Uji Eksekusi: Verifikasi bahwa pengujian protokol manual berfungsi

Langkah 4: Registrasi dengan Kode Claude

Menambahkan Server Anda

Daftarkan server Anda menggunakan lingkup yang tepat dan path absolut:

# Daftar dengan lingkup pengguna global untuk akses universal
claude mcp add --scope user my-first-server python3 ~/.claude-mcp-servers/my-first-server/server.py

Detail penting:

Verifikasi dan Pemecahan Masalah

# Verifikasi registrasi
claude mcp list

# Periksa masalah koneksi
claude mcp get my-first-server

Masalah registrasi umum:

Contoh Lanjutan: Integrasi API Cuaca

Melampaui Hello World

Sekarang setelah Anda memahami struktur dasar server MCP, mari bangun server yang lebih praktis yang mendemonstrasikan pola integrasi dunia nyata. Server API cuaca ini akan mengajarkan Anda:

Merencanakan Integrasi API Anda

Sebelum menulis kode, pertimbangkan aspek integrasi ini:

Pemilihan API: Kami akan menggunakan OpenWeatherMap API karena kesederhanaan dan tingkatan gratisnya

Alur Data: Permintaan pengguna → Validasi parameter → Panggilan API → Pemformatan respons → Respons Claude

Skenario Kesalahan: Kegagalan jaringan, kunci API tidak valid, respons salah format, pembatasan tarif (rate limiting)

Keamanan: Kunci API disimpan dalam variabel lingkungan, sanitasi input

Strategi Implementasi

Mari bangun server ini secara bertahap, mengimplementasikan setiap bagian dengan penanganan kesalahan penuh:

#!/usr/bin/env python3
import json
import sys
import os
import requests
from typing import Dict, Any

# Configuration - use environment variables for security
WEATHER_API_KEY = os.environ.get("OPENWEATHER_API_KEY", "your-api-key-here")

def get_weather(city: str) -> str:
    """Fetch current weather data for a specified city"""
    try:
        url = "<http://api.openweathermap.org/data/2.5/weather>"
        params = {
            "q": city,
            "appid": WEATHER_API_KEY,
            "units": "metric"
        }
        response = requests.get(url, params=params, timeout=10)
        data = response.json()

        if response.status_code == 200:
            temp = data["main"]["temp"]
            desc = data["weather"][0]["description"]
            humidity = data["main"]["humidity"]
            return f"Weather in {city}: {temp}°C, {desc.title()}, Humidity: {humidity}%"
        else:
            return f"Error fetching weather: {data.get('message', 'Unknown error')}"
    except requests.RequestException as e:
        return f"Network error: {str(e)}"
    except Exception as e:
        return f"Error processing weather data: {str(e)}"

def handle_tools_list(request_id: Any) -> Dict[str, Any]:
    """Enhanced tools list with weather functionality"""
    tools = [
        {
            "name": "get_weather",
            "description": "Get current weather conditions for any city worldwide",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name (e.g., 'London', 'Tokyo', 'New York')"
                    }
                },
                "required": ["city"]
            }
        }
    ]

    return {
        "jsonrpc": "2.0",
        "id": request_id,
        "result": {
            "tools": tools
        }
    }

def handle_tool_call(request_id: Any, params: Dict[str, Any]) -> Dict[str, Any]:
    """Enhanced tool execution with weather functionality"""
    tool_name = params.get("name")
    arguments = params.get("arguments", {})

    try:
        if tool_name == "get_weather":
            city = arguments.get("city")
            if not city:
                raise ValueError("City name is required")
            result = get_weather(city)
        else:
            raise ValueError(f"Unknown tool: {tool_name}")

        return {
            "jsonrpc": "2.0",
            "id": request_id,
            "result": {
                "content": [
                    {
                        "type": "text",
                        "text": result
                    }
                ]
            }
        }
    except Exception as e:
        return {
            "jsonrpc": "2.0",
            "id": request_id,
            "error": {
                "code": -32603,
                "message": str(e)
            }
        }

# Include the same main() function and other handlers from the basic example

Penjelasan Fitur Lanjutan

Keamanan Variabel Lingkungan: Kunci API dimuat dari variabel lingkungan, tidak pernah dikodekan secara permanen. Ini mencegah paparan yang tidak disengaja dalam kontrol versi.

Penanganan Kesalahan yang Kuat: Fungsi get_weather() menangani berbagai skenario kesalahan:

Skema Alat yang Ditingkatkan: Skema alat cuaca mencakup deskripsi dan contoh terperinci, membantu Kode Claude memahami cara menggunakan alat secara efektif.

Langkah 5: Manajemen Dependensi dan Konfigurasi Profesional

Membuat File Persyaratan yang Tepat

requests>=2.28.0
python-dotenv>=1.0.0

Strategi penetapan versi (version pinning): Menggunakan persyaratan versi minimum (>=) memastikan kompatibilitas sambil memungkinkan pembaruan keamanan. Untuk server produksi, pertimbangkan penetapan versi yang tepat.

Konfigurasi Lingkungan yang Aman

Buat file .env untuk manajemen konfigurasi:

# Konfigurasi API Cuaca
OPENWEATHER_API_KEY=kunci_api_asli_anda_di_sini

# Konfigurasi Server
MCP_LOG_LEVEL=INFO
MCP_DEBUG=false

# Opsional: Pembatasan tarif
MCP_MAX_REQUESTS_PER_MINUTE=60

Praktik terbaik keamanan:

Instalasi dan Isolasi Dependensi

# Buat lingkungan virtual untuk isolasi
python3 -m venv mcp-env
source mcp-env/bin/activate  # Di Windows: mcp-env\\\\Scripts\\\\activate

# Instal dependensi
pip install -r requirements.txt

# Verifikasi instalasi
python3 -c "import requests; print('Dependencies installed successfully')"

Mengapa lingkungan virtual penting: Isolasi mencegah konflik dependensi antara server MCP yang berbeda dan instalasi Python sistem Anda.

Menguji dan Men-debug Server MCP Anda

Strategi Pengujian Komprehensif

Menguji server MCP memerlukan pendekatan berlapis karena Anda berurusan dengan kepatuhan protokol dan kebenaran fungsional. Strategi pengujian yang sistematis mencegah masalah mencapai produksi dan membuat debugging jauh lebih mudah.

Piramida Pengujian untuk Server MCP

  1. Unit Tests: Pengujian fungsi individual
  2. Protocol Tests: Verifikasi kepatuhan JSON-RPC
  3. Integration Tests: Pengujian interaksi Kode Claude
  4. End-to-End Tests: Validasi alur kerja penuh

Lapisan 1: Pengujian Protokol Manual

Menguji Metode Inti MCP

Sebelum integrasi apa pun, verifikasi server Anda mengimplementasikan protokol MCP dengan benar:

# Uji jabat tangan inisialisasi
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 server.py

Struktur respons yang diharapkan:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {"tools": {}},
    "serverInfo": {"name": "your-server", "version": "1.0.0"}
  }
}

Menguji Penemuan Alat

# Uji titik akhir daftar alat
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python3 server.py

Daftar periksa validasi:

Menguji Eksekusi Alat

# Uji fungsionalitas alat sebenarnya
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"London"}}}' | python3 server.py

Apa yang harus diverifikasi:

Lapisan 2: Kerangka Kerja Pengujian Otomatis

Membuat Skrip Pengujian

Buat file test_server.py untuk pengujian otomatis:

#!/usr/bin/env python3
import json
import subprocess
import sys

def test_mcp_method(method, params=None):
    """Test a specific MCP method"""
    request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": method,
        "params": params or {}
    }

    try:
        result = subprocess.run(
            [sys.executable, "server.py"],
            input=json.dumps(request),
            capture_output=True,
            text=True,
            timeout=10
        )
        return json.loads(result.stdout.strip())
    except Exception as e:
        return {"error": str(e)}

# Test suite
tests = [
    ("initialize", None),
    ("tools/list", None),
    ("tools/call", {"name": "hello_world", "arguments": {"name": "Test"}})
]

for method, params in tests:
    response = test_mcp_method(method, params)
    print(f"Testing {method}: {'✓ PASS' if 'result' in response else '✗ FAIL'}")

Lapisan 3: Pengujian Integrasi dengan Kode Claude

Registrasi dan Verifikasi Server

# Daftarkan server Anda
claude mcp add --scope user test-server python3 /full/path/to/server.py

# Verifikasi registrasi
claude mcp list | grep test-server

# Periksa kesehatan server
claude mcp get test-server

Pengujian Integrasi Langsung

# Mulai Kode Claude dalam mode uji
claude

# Di Kode Claude, uji penemuan alat
/mcp

# Uji eksekusi alat
mcp__test-server__hello_world name:"Integration Test"

Pola penamaan alat: Kode Claude memberi awalan alat dengan mcp__<nama-server>__<nama-alat> untuk menghindari konflik penamaan.

Teknik Debugging Tingkat Lanjut

Mengaktifkan Debug Logging

Tambahkan logging komprehensif ke server Anda:

import logging
import sys

# Konfigurasi logging ke stderr (tidak akan mengganggu JSON-RPC)
logging.basicConfig(
    level=logging.DEBUG,
    stream=sys.stderr,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger(__name__)

def handle_tool_call(request_id, params):
    logger.debug(f"Received tool call: {params}")
    # ... logika alat Anda
    logger.debug(f"Tool execution completed successfully")

Analisis Log Server MCP

Kode Claude menyimpan log untuk setiap server MCP:

# Lihat log terbaru (macOS)
tail -f ~/Library/Logs/Claude/mcp-server-*.log

# Lihat log terbaru (Linux)
tail -f ~/.config/claude/logs/mcp-server-*.log

# Cari kesalahan
grep -i error ~/Library/Logs/Claude/mcp-server-*.log

Pola Debugging Umum

Masalah: Server dimulai tetapi alat tidak muncul

Diagnosis: Periksa format respons tools/list

Solusi: Validasi kepatuhan skema JSON

Masalah: Panggilan alat gagal secara diam-diam

Diagnosis: Periksa penanganan kesalahan di tools/call

Solusi: Tambahkan penanganan pengecualian yang komprehensif

Masalah: Koneksi server terputus

Diagnosis: Periksa I/O tanpa buffer dan penanganan pengecualian yang tepat

Solusi: Verifikasi konfigurasi sys.stdout dan penanganan kesalahan loop utama

Pengujian Kinerja dan Keandalan

Pengujian Beban Server Anda

# Uji beberapa permintaan cepat
for i in {1..10}; do
  echo '{"jsonrpc":"2.0","id":'$i',"method":"tools/list","params":{}}' | python3 server.py &
done
wait

Pemantauan Memori dan Sumber Daya

# Pantau penggunaan sumber daya server
python3 -m memory_profiler server.py

# Periksa kebocoran memori selama operasi yang diperpanjang
python3 -m tracemalloc server.py

Pemecahan Masalah Umum

Masalah Tingkat Protokol

  1. Respons JSON tidak valid: Gunakan json.loads() untuk memvalidasi output
  2. Bidang yang diperlukan hilang: Periksa kepatuhan spesifikasi MCP
  3. Kode kesalahan tidak tepat: Gunakan kode kesalahan JSON-RPC standar

Masalah Integrasi

  1. Server tidak muncul: Verifikasi izin file dan path Python
  2. Alat tidak dapat diakses: Periksa konfigurasi dan registrasi lingkup
  3. Kegagalan otentikasi: Pastikan inisialisasi MCP yang tepat

Praktik Terbaik dan Pertimbangan Keamanan

Penanganan Kesalahan Siap Produksi

Mengimplementasikan Validasi yang Kuat

Penanganan kesalahan di server MCP harus komprehensif karena kegagalan dapat merusak seluruh rantai komunikasi dengan Kode Claude. Implementasikan validasi di berbagai tingkatan:

def validate_arguments(arguments: Dict[str, Any], required: List[str]):
    """Validate required arguments are present"""
    missing = [field for field in required if field not in arguments]
    if missing:
        raise ValueError(f"Missing required fields: {', '.join(missing)}")

def handle_tool_call(request_id: Any, params: Dict[str, Any]) -> Dict[str, Any]:
    """Tool execution with proper validation"""
    try:
        tool_name = params.get("name")
        arguments = params.get("arguments", {})

        # Validate before processing
        if tool_name == "get_weather":
            validate_arguments(arguments, ["city"])

        # Process tool logic here

    except ValueError as ve:
        return create_error_response(request_id, -32602, str(ve))
    except Exception as e:
        return create_error_response(request_id, -32603, f"Internal error: {str(e)}")

Standar Respons Kesalahan

Ikuti konvensi kode kesalahan JSON-RPC 2.0:

Kerangka Kerja Keamanan Komprehensif

1. Manajemen Rahasia

Jangan pernah mengkodekan informasi sensitif secara permanen. Gunakan pendekatan berlapis untuk konfigurasi:

import os
from pathlib import Path

def load_config():
    """Load configuration with fallback hierarchy"""
    # 1. Environment variables (highest priority)
    api_key = os.environ.get("API_KEY")

    # 2. Local .env file
    if not api_key:
        env_path = Path(".env")
        if env_path.exists():
            # Load from .env file
            pass

    # 3. System keyring (production)
    if not api_key:
        try:
            import keyring
            api_key = keyring.get_password("mcp-server", "api_key")
        except ImportError:
            pass

    if not api_key:
        raise ValueError("API key not found in any configuration source")

    return {"api_key": api_key}

2. Sanitasi dan Validasi Input

Implementasikan validasi input yang ketat untuk mencegah serangan injeksi:

import re
from typing import Any, Dict

def sanitize_string_input(value: str, max_length: int = 100) -> str:
    """Sanitize string inputs"""
    if not isinstance(value, str):
        raise ValueError("Expected string input")

    # Remove potentially dangerous characters
    sanitized = re.sub(r'[<>"\\\\']', '', value)

    # Limit length to prevent DoS
    if len(sanitized) > max_length:
        raise ValueError(f"Input too long (max {max_length} characters)")

    return sanitized.strip()

def validate_city_name(city: str) -> str:
    """Validate city name input"""
    sanitized = sanitize_string_input(city, 50)

    # Allow only letters, spaces, and common punctuation
    if not re.match(r'^[a-zA-Z\\\\s\\\\-\\\\.]+$', sanitized):
        raise ValueError("Invalid city name format")

    return sanitized

3. Pembatasan Tarif dan Perlindungan Sumber Daya

Implementasikan pembatasan tarif untuk mencegah penyalahgunaan:

import time
from collections import defaultdict
from threading import Lock

class RateLimiter:
    def __init__(self, max_requests: int = 60, window_seconds: int = 60):
        self.max_requests = max_requests
        self.window_seconds = window_seconds
        self.requests = defaultdict(list)
        self.lock = Lock()

    def allow_request(self, client_id: str = "default") -> bool:
        """Check if request is allowed under rate limit"""
        now = time.time()

        with self.lock:
            # Clean old requests
            self.requests[client_id] = [
                req_time for req_time in self.requests[client_id]
                if now - req_time < self.window_seconds
            ]

            # Check limit
            if len(self.requests[client_id]) >= self.max_requests:
                return False

            # Record this request
            self.requests[client_id].append(now)
            return True

# Global rate limiter instance
rate_limiter = RateLimiter()

Logging dan Pemantauan Tingkat Lanjut

Implementasi Structured Logging

Gunakan structured logging untuk debugging dan pemantauan yang lebih baik:

import logging
import json
import sys
from datetime import datetime

class MCPFormatter(logging.Formatter):
    """Custom formatter for MCP server logs"""

    def format(self, record):
        log_entry = {
            "timestamp": datetime.utcnow().isoformat(),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
        }

        # Add extra context if available
        if hasattr(record, 'tool_name'):
            log_entry["tool_name"] = record.tool_name
        if hasattr(record, 'request_id'):
            log_entry["request_id"] = record.request_id

        return json.dumps(log_entry)

# Configure structured logging
logger = logging.getLogger(__name__)
handler = logging.StreamHandler(sys.stderr)
handler.setFormatter(MCPFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

Pemantauan Kinerja

Lacak metrik kinerja server:

import time
import statistics
from collections import deque

class PerformanceMonitor:
    def __init__(self, max_samples: int = 1000):
        self.response_times = deque(maxlen=max_samples)
        self.error_count = 0
        self.request_count = 0

    def record_request(self, duration: float, success: bool):
        """Record request metrics"""
        self.request_count += 1
        self.response_times.append(duration)

        if not success:
            self.error_count += 1

    def get_stats(self) -> Dict[str, Any]:
        """Get current performance statistics"""
        if not self.response_times:
            return {"no_data": True}

        return {
            "total_requests": self.request_count,
            "error_rate": self.error_count / self.request_count,
            "avg_response_time": statistics.mean(self.response_times),
            "p95_response_time": statistics.quantiles(self.response_times, n=20)[18],
            "p99_response_time": statistics.quantiles(self.response_times, n=100)[98]
        }

# Global performance monitor
perf_monitor = PerformanceMonitor()

Strategi Deployment dan Pemeliharaan

Manajemen Versi

Implementasikan versioning yang tepat untuk server MCP Anda:

__version__ = "1.2.3"
__mcp_version__ = "2024-11-05"

def get_server_info():
    """Return server information for MCP initialize"""
    return {
        "name": "my-production-server",
        "version": __version__,
        "mcp_protocol_version": __mcp_version__,
        "capabilities": ["tools", "resources"],  # Declare what you support
    }

Implementasi Health Check

Tambahkan kemampuan health check untuk pemantauan:

def handle_health_check(request_id: Any) -> Dict[str, Any]:
    """Health check endpoint for monitoring"""
    try:
        # Test core functionality
        test_db_connection()  # Example health check
        test_external_apis()  # Example health check

        return {
            "jsonrpc": "2.0",
            "id": request_id,
            "result": {
                "status": "healthy",
                "timestamp": datetime.utcnow().isoformat(),
                "version": __version__,
                "uptime_seconds": time.time() - start_time,
                "performance": perf_monitor.get_stats()
            }
        }
    except Exception as e:
        return {
            "jsonrpc": "2.0",
            "id": request_id,
            "result": {
                "status": "unhealthy",
                "error": str(e),
                "timestamp": datetime.utcnow().isoformat()
            }
        }

Penanganan Shutdown yang Anggun

Implementasikan pembersihan yang tepat saat server mati:

import signal
import sys

class MCPServer:
    def __init__(self):
        self.running = True
        self.active_requests = set()

        # Register signal handlers
        signal.signal(signal.SIGINT, self.shutdown_handler)
        signal.signal(signal.SIGTERM, self.shutdown_handler)

    def shutdown_handler(self, signum, frame):
        """Handle graceful shutdown"""
        logger.info(f"Received signal {signum}, initiating graceful shutdown")
        self.running = False

        # Wait for active requests to complete
        timeout = 30  # seconds
        start_time = time.time()

        while self.active_requests and (time.time() - start_time) < timeout:
            time.sleep(0.1)

        logger.info("Shutdown complete")
        sys.exit(0)

Kasus Penggunaan Dunia Nyata dan Aplikasi Tingkat Lanjut

Pola Integrasi Perusahaan

Server MCP unggul di lingkungan perusahaan di mana Kode Claude perlu berintegrasi dengan sistem bisnis yang ada. Berikut adalah pola integrasi yang terbukti:

Server Integrasi Database

Otomatisasi Alur Kerja Pengembangan

Pemantauan dan Operasi Sistem

Pola Arsitektur Tingkat Lanjut

Orkestrasi Multi-Server

Untuk alur kerja yang kompleks, rancang server MCP yang berkoordinasi satu sama lain:

# Pola koordinasi server
def coordinate_workflow(workflow_id: str, steps: List[Dict]) -> Dict:
    """Coordinate multi-step workflow across servers"""
    results = {}

    for step in steps:
        server_name = step["server"]
        tool_name = step["tool"]
        params = step["params"]

        # Call other MCP server through Claude Code
        result = call_mcp_tool(server_name, tool_name, params)
        results[step["id"]] = result

        # Handle dependencies between steps
        if step.get("depends_on"):
            inject_dependencies(params, results, step["depends_on"])

    return {"workflow_id": workflow_id, "results": results}

Caching dan Optimasi Kinerja

Implementasikan caching cerdas untuk data yang sering diminta:

import hashlib
import pickle
from datetime import datetime, timedelta

class IntelligentCache:
    def __init__(self, default_ttl: int = 3600):
        self.cache = {}
        self.default_ttl = default_ttl

    def get_cache_key(self, tool_name: str, params: Dict) -> str:
        """Generate consistent cache key"""
        key_data = f"{tool_name}:{json.dumps(params, sort_keys=True)}"
        return hashlib.md5(key_data.encode()).hexdigest()

    def get(self, tool_name: str, params: Dict) -> Optional[Any]:
        """Get cached result if valid"""
        key = self.get_cache_key(tool_name, params)

        if key in self.cache:
            data, expiry = self.cache[key]
            if datetime.now() < expiry:
                return data
            else:
                del self.cache[key]

        return None

    def set(self, tool_name: str, params: Dict, result: Any, ttl: Optional[int] = None):
        """Cache result with TTL"""
        key = self.get_cache_key(tool_name, params)
        expiry = datetime.now() + timedelta(seconds=ttl or self.default_ttl)
        self.cache[key] = (result, expiry)

Strategi Deployment Produksi

Deployment dalam Kontainer

Kemaskan server MCP Anda sebagai kontainer Docker untuk deployment yang konsisten:

FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \\\\
    curl \\\\
    && rm -rf /var/lib/apt/lists/*

# Copy and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY server.py .
COPY config/ ./config/

# Create non-root user
RUN useradd -m -s /bin/bash mcpuser
USER mcpuser

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \\\\
    CMD python3 -c "import requests; requests.get('<http://localhost:8080/health>')"

CMD ["python3", "server.py"]

Deployment Kubernetes

Deploy server MCP di Kubernetes untuk skalabilitas dan keandalan:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-weather-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-weather-server
  template:
    metadata:
      labels:
        app: mcp-weather-server
    spec:
      containers:
      - name: mcp-server
        image: your-registry/mcp-weather-server:latest
        ports:
        - containerPort: 8080
        env:
        - name: OPENWEATHER_API_KEY
          valueFrom:
            secretKeyRef:
              name: mcp-secrets
              key: openweather-api-key
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10

Pertimbangan Skalabilitas dan Kinerja

Pola Skalabilitas Horizontal

Rancang server MCP Anda untuk mendukung skalabilitas horizontal:

  1. Desain Stateless: Jaga server agar stateless untuk memungkinkan replikasi yang mudah
  2. Load Balancing: Distribusi permintaan di beberapa instance server
  3. Database Pooling: Gunakan connection pooling untuk server yang didukung database
  4. Strategi Caching: Implementasikan Redis atau Memcached untuk shared caching

Teknik Optimasi Kinerja

import asyncio
import aiohttp
from concurrent.futures import ThreadPoolExecutor

class HighPerformanceMCPServer:
    def __init__(self):
        self.executor = ThreadPoolExecutor(max_workers=10)
        self.session = None

    async def async_tool_call(self, tool_name: str, params: Dict) -> Dict:
        """Handle tool calls asynchronously"""
        if not self.session:
            self.session = aiohttp.ClientSession()

        # Use async operations for I/O bound tasks
        if tool_name == "web_search":
            return await self.async_web_search(params)
        elif tool_name == "database_query":
            return await self.async_database_query(params)
        else:
            # Use thread pool for CPU-bound tasks
            loop = asyncio.get_event_loop()
            return await loop.run_in_executor(
                self.executor,
                self.sync_tool_call,
                tool_name,
                params
            )

Kesimpulan dan Langkah Selanjutnya

Menguasai Pengembangan MCP

Membangun server MCP untuk Kode Claude mewakili pergeseran paradigma dalam pengembangan aplikasi AI. Tidak seperti integrasi API tradisional yang memerlukan koneksi yang dikodekan secara permanen, MCP menyediakan antarmuka yang dinamis dan dapat ditemukan yang membuat asisten AI benar-benar dapat diperluas.

Sepanjang panduan komprehensif ini, Anda telah mempelajari:

Keterampilan Dasar:

Kesiapan Produksi:

Kemampuan Tingkat Lanjut:

Pendekatan Pengembangan Strategis

Fase 1: Pembangunan Fondasi (Minggu 1-2)

Mulailah dengan server sederhana dan bertujuan tunggal untuk memahami protokol:

Fase 2: Perluasan Integrasi (Minggu 3-4)

Bangun server yang lebih kompleks yang berintegrasi dengan sistem yang ada:

Fase 3: Deployment Perusahaan (Bulan 2+)

Deploy server siap produksi dengan dukungan operasional penuh:

Strategi Sukses Jangka Panjang

Keterlibatan Komunitas

Perbaikan Berkelanjutan

Peluang Inovasi

Masa Depan Pengembangan MCP

Model Context Protocol mewakili fondasi untuk ekosistem baru aplikasi terintegrasi AI. Saat Anda membangun server MCP, Anda tidak hanya membuat alat untuk Kode Claude—Anda membangun komponen yang dapat digunakan kembali yang akan berfungsi di seluruh ekosistem asisten AI yang kompatibel dengan MCP yang terus berkembang.

Investasi Anda dalam pengembangan MCP memberikan keuntungan melalui:

Pengingat Sukses Kritis

Saat Anda memulai perjalanan pengembangan MCP, ingatlah prinsip-prinsip penting ini:

  1. Penguasaan lingkup konfigurasi: Selalu gunakan -scope user untuk server pengembangan kecuali Anda secara khusus memerlukan pembatasan tingkat proyek
  2. Keamanan utama: Jangan pernah mengkodekan rahasia secara permanen, selalu validasi input, implementasikan pembatasan tarif
  3. Kelengkapan penanganan kesalahan: Antisipasi dan tangani semua mode kegagalan dengan anggun
  4. Ketelitian pengujian: Uji kepatuhan protokol, fungsionalitas, dan integrasi
  5. Kualitas dokumentasi: Dokumentasikan server Anda untuk kolaborasi tim dan pemeliharaan

Mendapatkan Bantuan dan Sumber Daya

Ketika Anda menghadapi tantangan:

Mulailah membangun hari ini, iterasi dengan cepat, dan bergabunglah dengan komunitas pengembang yang terus berkembang yang memperluas kemampuan AI melalui Model Context Protocol. Server MCP kustom Anda akan membuka kemungkinan baru untuk alur kerja yang dibantu AI yang baru mulai kita bayangkan.

Ingat: setiap integrasi kompleks dimulai dengan server "Hello World" yang sederhana. Mulailah dengan dasar-dasar, kuasai fundamental, dan secara bertahap bangun alat terintegrasi AI yang akan mengubah cara Anda bekerja.

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda agar dapat bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh