Cara Membuat Server MCP: Tutorial Langkah demi Langkah dengan Python dan TypeScript (2026)

Anda bisa membuat server MCP yang benar-benar dipanggil oleh Claude dalam waktu sekitar 15 menit. Kami mengujinya di Node 20 dan Python 3.11: alat add yang berfungsi, berjalan melalui stdio, dan terdeteksi oleh Claude Desktop, membutuhkan waktu 14 menit pada percobaan pertama dan kurang dari 5 menit setelah Anda memahami strukturnya. Tutorial ini membangun server yang sama dua kali, sekali di Python dengan FastMCP 2.x, sekali di TypeScript dengan @modelcontextprotocol/sdk 1.x — sehingga Anda dapat memilih stack teknologi Anda dan menyalin kode nyata. Jika Anda ingin mempelajari arsitektur dan teori protokol terlebih dahulu, panduan konsep Model Context Protocol kami memilikinya; di sini kita hanya fokus pada pembangunan.

Mulai Cepat Server MCP: Apa yang Akan Anda Bangun

Server MCP adalah program kecil yang mengekspos alat, data, dan templat prompt kepada klien AI seperti Claude, Cursor, atau VS Code melalui Model Context Protocol. Anda menulis server sekali, dan klien apa pun yang kompatibel dengan MCP dapat memanggilnya. Dalam tutorial ini, Anda akan membangun server dengan dua alat (kalkulator add dan helper fetch_url), menjalankannya secara lokal melalui stdio, mengujinya, dan menghubungkannya ke klien nyata.

Berikut adalah semua yang Anda butuhkan sebelum memulai.

Kedua jalur menghasilkan server yang berperilaku identik. Pilih bahasa yang sudah digunakan oleh tim Anda. Jika Anda tidak memiliki preferensi, mulailah dengan Python, karena FastMCP membuat server pertama lebih ringkas.

Apa Sebenarnya yang Diekspos oleh Server MCP?

Sebelum Anda menulis kode, penting untuk mengetahui tiga hal yang dapat ditawarkan oleh server. Server MCP mengekspos alat (fungsi yang dapat dipanggil oleh model, seperti "cari database"), sumber daya (data baca-saja yang dapat dimuat oleh model, seperti file atau rekaman), dan prompt (templat prompt yang dapat digunakan kembali). Sebagian besar server yang Anda bangun akan berfokus pada alat; sumber daya dan prompt bersifat opsional.

Definisi server MCP: sebuah proses yang berbicara menggunakan Model Context Protocol dan mengiklankan daftar alat, sumber daya, dan prompt yang dapat ditemukan dan dipanggil oleh klien AI saat runtime.

Klien (misalnya, Claude Desktop) bertindak sebagai host. Ia meluncurkan atau terhubung ke server Anda, bertanya "alat apa yang Anda miliki?", dan kemudian memanggilnya ketika model memutuskan bahwa suatu alat berguna. Anda tidak pernah memanggil model dari dalam server. Alurnya berjalan sebaliknya.

Arah tersebut sangat penting. Server Anda adalah penyedia pasif. Ia menunggu klien terhubung, menjawab permintaan penemuan, dan menjalankan alat apa pun yang dipanggil. Simpan model mental ini dan sisa tutorial ini akan menjadi lebih mudah dipahami.

Cara Membuat Server MCP di Python (Langkah demi Langkah)

Python adalah jalur tercepat menuju server yang berjalan karena FastMCP menangani plumbing protokol dan mengubah fungsi biasa menjadi alat dengan dekorator. Semua di bawah ini menggunakan SDK Python resmi. Berikut adalah empat langkahnya.

Langkah 1: Siapkan proyek. Gunakan uv, yang kini menjadi standar untuk proyek MCP Python:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Jika Anda lebih memilih pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Langkah 2: Tulis server. Buat server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Dua hal yang perlu diperhatikan. Docstring menjadi deskripsi alat yang dibaca oleh model, jadi tulislah seperti instruksi. Dan hint tipe (a: int) menjadi skema input secara otomatis, sehingga FastMCP menghasilkan JSON Schema untuk Anda.

Langkah 3: Jalankan. mcp.run() memulai server di stdio, transport yang diluncurkan klien secara lokal. Anda tidak menjalankannya secara langsung selama pengembangan; klien yang meluncurkannya. Untuk tes cepat, gunakan runner dev:

uv run mcp dev server.py

Langkah 4: Kembalikan output yang bersih. Sebuah jebakan yang perlu ditandai sekarang: kembalikan string atau nilai bertipe, bukan dict bersarang mentah yang Anda harap akan dirender. Kita akan kembali membahas alasannya di bagian produksi, tetapi versi singkatnya adalah bahwa tipe kembalian yang ambigu dapat dipotong secara diam-diam di beberapa klien.

Itulah server MCP Python yang lengkap. Dua alat, panggilan jaringan nyata, skema otomatis. Selanjutnya, hal yang sama di TypeScript.

Cara Membuat Server MCP di TypeScript (Langkah demi Langkah)

Jalur TypeScript menggunakan SDK TypeScript resmi secara langsung dan zod untuk validasi input. Ini sedikit lebih verbose daripada FastMCP, tetapi tipenya sangat baik dan dapat dideploy dengan bersih ke host Node.

Langkah 1: Siapkan proyek.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Langkah 2: Tulis server. Buat server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

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

Langkah 3: Jalankan. Selama pengembangan: npx tsx server.ts. Untuk produksi, kompilasi dengan tsc dan jalankan .js yang telah dibangun dengan Node. Perhatikan bentuk kembalian: setiap alat mengembalikan { content: [{ type: "text", text: ... }] }. Array content eksplisit tersebut adalah ekuivalen TypeScript dari aturan "kembalikan string bersih" dari Python. SDK menginginkan blok konten bertipe, bukan objek mentah.

Langkah 4: Validasi input dengan zod. Skema z.string().url() menolak input buruk sebelum handler Anda berjalan, yang persis seperti yang Anda inginkan ketika model menghasilkan argumen.

Dua alat yang sama, perilaku yang sama, TypeScript yang idiomatik. Sekarang mari kita putuskan bagaimana klien harus menjangkau server Anda.

stdio vs Streamable HTTP: Transport Mana yang Harus Anda Gunakan?

Server MCP berkomunikasi melalui salah satu dari dua transport. stdio menjalankan server sebagai subproses lokal yang diluncurkan klien dan berkomunikasi melalui input/output standar. Streamable HTTP menjalankan server sebagai layanan jaringan yang dihubungi klien melalui HTTP. Pilih berdasarkan tempat server perlu berada.

Aturan praktisnya: bangun dan uji di stdio, lalu beralih ke Streamable HTTP hanya ketika lebih dari satu orang atau mesin membutuhkan server tersebut. Sebagian besar server tidak perlu keluar dari stdio. Panggilan mcp.run() dan StdioServerTransport() di atas sudah menggunakan stdio, jadi Anda siap untuk pengembangan.

Cara Menguji Server MCP Anda dengan Inspector

Sebelum Anda menghubungkan server ke Claude, ujilah secara terisolasi dengan MCP Inspector. Ini adalah UI browser yang terhubung ke server Anda, mendaftar alat-alatnya, dan memungkinkan Anda memanggilnya secara manual. Jalankan terhadap server Anda:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Inspector membuka halaman lokal di mana Anda dapat melihat alat add dan fetch_url Anda, melakukan panggilan uji, dan membaca respons mentah. Ini adalah kebiasaan terbaik tunggal untuk pengembangan MCP. Jika skema alat rusak atau nilai kembalian salah, Anda akan melihatnya di sini dalam hitungan detik daripada menatap kegagalan diam di dalam Claude. Kami menangkap skema input yang buruk dengan cara ini yang jika tidak akan memakan waktu satu putaran debugging penuh melalui klien. Uji di Inspector terlebih dahulu, setiap saat.

Cara Menghubungkan Server MCP Anda ke Claude Desktop, Claude Code, dan Cursor

Setelah Inspector puas, arahkan klien nyata ke server Anda. Setiap klien membaca file konfigurasi yang memberitahukannya cara meluncurkan server Anda melalui stdio.

Claude Desktop. Edit claude_desktop_config.json (di macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Mulai ulang Claude Desktop dan alat Anda akan muncul di bawah ikon konektor.

Claude Code. Tambahkan server dengan satu perintah dari proyek Anda: claude mcp add demo-server -- uv run server.py. Claude Code menyimpannya di konfigurasi proyek Anda dan memuatnya saat peluncuran. Jika Anda juga menggunakan hook untuk menskrip Claude Code, panduan hook Claude Code kami berpasangan dengan baik dengan alat MCP kustom.

Cursor. Tambahkan blok mcpServers yang sama ke .cursor/mcp.json di root proyek Anda. Bentuknya cocok dengan Claude Desktop. Untuk contoh dunia nyata server MCP yang berjalan di dalam Claude Code, lihat bagaimana kami menghubungkan Higgsfield ke Claude Code.

Gunakan path absolut di setiap konfigurasi. Path relatif adalah alasan paling umum server gagal diluncurkan.

Deploy Server MCP ke Produksi (Auth dan Hosting)

Ketika server Anda perlu dibagikan, pindahkan dari stdio ke Streamable HTTP dan tambahkan tiga hal: autentikasi, penanganan error, dan host.

• Autentikasi. Server MCP jarak jauh harus menggunakan OAuth 2.1 sesuai spesifikasi otorisasi MCP. Untuk alat internal, pemeriksaan bearer-token pada endpoint HTTP adalah minimum yang pragmatis. Jangan pernah merilis server alat publik tanpa autentikasi, karena alat yang menjalankan SQL atau mengakses API internal adalah permukaan serangan yang hidup.
• Penanganan error. Bungkus badan alat dalam try/except (atau try/catch) dan kembalikan pesan error bertipe daripada melemparkannya. Model menangani "kueri gagal, inilah alasannya" jauh lebih baik daripada koneksi yang putus.
• Hosting. Platform apa pun yang menjalankan proses Node atau Python jangka panjang berfungsi: VPS kecil, Fly.io, Railway, atau kontainer di infrastruktur Anda sendiri. Jaga proses tetap hangat, karena cold start menambah latensi pada panggilan alat pertama.
• Konkurensi dan biaya. Jika alat Anda memanggil LLM atau API berbayar di hilir, letakkan gateway di depannya. Rangkuman kami tentang alat gateway LLM mencakup pembatasan laju dan fallback, dan alat rekayasa konteks membantu mencegah output alat membengkakkan jendela konteks model.

Untuk Python, ubah panggilan run menjadi mcp.run(transport="streamable-http"); untuk TypeScript, ganti StdioServerTransport dengan StreamableHTTPServerTransport dari SDK. Definisi alat tidak berubah sama sekali — itulah poin dari abstraksi transport.

Apa yang Kami Pelajari dari Meluncurkan Server MCP di Produksi

Kami telah membangun server MCP untuk penggunaan internal di Techsy, dan beberapa pelajaran hanya muncul setelah lalu lintas nyata menghantamnya. Berikut adalah apa yang kami ukur dan di mana kami mengalami masalah.

Server pertama yang kami luncurkan adalah alat kueri Postgres baca-saja yang dibangun dengan FastMCP 2.x pada SDK Python mcp 1.x, yang kemudian ditulis ulang di @modelcontextprotocol/sdk 1.x untuk perbandingan. Pada stack 2026 (Node 20, Python 3.11), panggilan alat stdio lokal menambahkan overhead transport sekitar 8 hingga 12 ms per panggilan. Setelah kami memindahkan server yang sama ke Streamable HTTP di VPS, biaya per panggilan naik menjadi 40 hingga 70 ms, hampir seluruhnya karena round-trip jaringan daripada biaya protokol. Cold-start FastMCP sekitar 300 ms untuk proses, itulah sebabnya kami menjaga proses produksi tetap hangat.

Jebakan yang memakan waktu sekitar dua jam: alat yang mengembalikan dict Python mentah dirender dengan baik di Inspector tetapi kembali terpotong di dalam Claude Desktop. Membungkus nilai kembalian sebagai string teks bertype memperbaikinya secara instan. Itulah sebabnya tutorial ini mengembalikan string dan blok teks content di mana-mana daripada objek bersarang. Kebiasaan lain yang langsung membuahkan hasil adalah menjalankan setiap server melalui npx @modelcontextprotocol/inspector sebelum menyentuh konfigurasi klien, yang mengungkapkan skema input yang rusak pada penulisan ulang TypeScript yang jika tidak akan gagal secara diam-diam di Cursor.

Jika Anda memilih alat mana yang akan dibangun ke dalam server di tempat pertama, daftar kami tentang server MCP terbaik di 2026 adalah bank ide yang bagus.

Bagaimana Techsy Mendekati Pengembangan MCP

Di Techsy, kami membangun server MCP sebagai bagian dari sistem agen AI yang kami kirimkan untuk klien, menghubungkan agen ke database internal, CRM, dan API melalui lapisan alat bertipe. Pendekatan kami adalah mulai secara sempit (satu alat yang teruji dengan baik melalui stdio), memvalidasinya di Inspector, lalu meningkatkannya ke layanan HTTP terautentikasi hanya ketika lebih dari satu agen membutuhkannya. Kami memasangkan server kustom dengan Claude Agent SDK ketika logika agen menjadi kompleks.

Itulah versi jujurnya: sebagian besar tim terlalu berlebihan membangun server pertama mereka. Anda jarang membutuhkan HTTP, OAuth, dan selusin alat pada hari pertama. Jika Anda ingin sepasang mata tambahan pada integrasi MCP, dapatkan konsultasi gratis dan kami akan memberi tahu Anda apakah itu pekerjaan stdio satu alat atau sesuatu yang benar-benar membutuhkan infrastruktur.

Pertanyaan yang Sering Diajukan

Haruskah saya membangun server MCP saya di Python atau TypeScript?

Gunakan apa pun yang sudah dikirimkan oleh tim Anda. Python dengan FastMCP adalah jalur terpendek ke server pertama yang berjalan karena dekorator mengubah fungsi menjadi alat. TypeScript dengan SDK resmi sedikit lebih verbose tetapi memberikan tipe yang sangat baik dan dideploy dengan bersih ke host Node. Keduanya menghasilkan server yang berperilaku identik bagi klien.

Apakah saya memerlukan framework seperti FastMCP untuk membangun server MCP?

Tidak, tetapi itu membantu. FastMCP disertakan dalam SDK Python mcp resmi dan menghapus sebagian besar boilerplate protokol. Anda dapat menggunakan API Server tingkat rendah untuk kontrol yang lebih halus, tetapi untuk hampir setiap server, FastMCP (Python) atau McpServer (TypeScript) adalah alat yang tepat dan membutuhkan kode yang jauh lebih sedikit.

Bagaimana cara men-debug server MCP yang tidak berfungsi?

Jalankan melalui MCP Inspector terlebih dahulu: npx @modelcontextprotocol/inspector diikuti oleh perintah run Anda. Inspector mendaftar alat Anda dan memungkinkan Anda memanggilnya secara langsung, sehingga Anda dapat memastikan server berfungsi sebelum menyalahkan klien. Jika Inspector baik-baik saja tetapi klien tidak, periksa apakah konfigurasi Anda menggunakan path absolut dan bahwa Anda telah memulai ulang klien.

Apakah FastMCP merupakan bagian resmi dari MCP?

Ya. FastMCP dibundel dengan SDK Python Model Context Protocol resmi sebagai antarmuka server tingkat tinggi. Dekorator @mcp.tool() yang Anda gunakan adalah cara yang direkomendasikan untuk membangun server Python, bukan add-on pihak ketiga.

Apa perbedaan antara server MCP lokal dan jarak jauh?

Server lokal berjalan di mesin Anda melalui stdio, diluncurkan oleh klien sebagai subproses, terbaik untuk alat pribadi dan pengembangan. Server jarak jauh berjalan sebagai layanan web melalui Streamable HTTP dan dapat dijangkau oleh banyak klien, yang memerlukan autentikasi OAuth 2.1. Bangun lokal terlebih dahulu, pergi ke jarak jauh hanya saat berbagi.

Bahasa apa saja yang dapat saya gunakan untuk membangun server MCP?

Model Context Protocol memiliki SDK resmi untuk Python, TypeScript, Java, Kotlin, dan C#, dengan SDK komunitas dalam bahasa lain. Karena MCP adalah protokol kabel, bahasa apa pun yang dapat membaca dan menulis JSON-RPC melalui stdio atau HTTP dapat mengimplementasikan server, tetapi SDK resmi menghemat pekerjaan tersebut untuk Anda.

Apakah server MCP bekerja dengan ChatGPT dan Gemini, atau hanya Claude?

MCP adalah standar terbuka yang diadopsi di seluruh ekosistem AI agentic, termasuk ChatGPT, Gemini, Cursor, dan VS Code Copilot. Satu server yang Anda bangun bekerja dengan klien yang kompatibel apa pun. Anda tidak menulis integrasi terpisah per model, yang merupakan tujuan utama dari protokol tersebut.

Berapa lama waktu yang dibutuhkan untuk membangun server MCP yang berfungsi?

Server pertama dengan satu atau dua alat yang berjalan melalui stdio membutuhkan waktu sekitar 15 menit setelah runtime Anda diinstal. Kami mengukur 14 menit untuk pemula di Node 20 dan kurang dari 5 menit untuk pembangunan ulang. Menambahkan autentikasi, transport HTTP, dan hosting produksi adalah yang memakan waktu nyata, bukan server itu sendiri.

Tentang Penulis

Mert Batur Gurbuz adalah Co-Founder Techsy.io, di mana timnya mengirimkan agen AI, sistem otomatisasi, dan pipeline voice/SDR untuk klien B2B. Ia belajar di University of Birmingham dan menulis tentang stack tooling LLM yang benar-benar digunakan oleh tim Techsy dalam produksi. Terhubung di LinkedIn.

Mert Batur Gurbuz, Co-Founder, Techsy.io, University of Birmingham