mcp-server-architect · diff
git:20260726.f972adb to git:20260729.f16bff5
134 added, 76 removed. Audit A to A.
---
name: mcp-server-architect
description: "Expert guide for designing, building, and security-hardening Model Context Protocol (MCP) servers and tool integrations in TypeScript, Python, and Go / Panduan ahli merancang, membangun, dan mengamankan server Model Context Protocol (MCP) dan integrasi tool dalam TypeScript, Python, dan Go."
author: "Roedy Rustam"
---
- # Model Context Protocol (MCP) Server Architect
+ # MCP Server Architect (v1.9+ Edition)
[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
---
<a name="english"></a>
## English
### Description
- Production-grade architecture guide for designing, building, testing, and securing **Model Context Protocol (MCP)** servers. MCP is the open protocol standardizing how Artificial Intelligence (AI) agents (such as Claude Desktop, Antigravity, Cursor, Windsurf, and custom LLM applications) discover and execute tools, read structured resources, and load prompt templates over JSON-RPC 2.0.
+ Expert guide for designing, building, and security-hardening **Model Context Protocol (MCP)** servers and client integrations. Covers MCP v1.9+ specification (including the new Streamable HTTP transport), tool/resource/prompt design, Zod validation, OAuth 2.1 authorization, and multi-server orchestration patterns for production AI applications.
### Trigger Conditions
- - Designing or implementing a custom MCP Server in **TypeScript**, **Python**, or **Go**.
- - Exposing databases, APIs, local CLI tools, or cloud infrastructure to AI agents.
- - Configuring MCP transports (`stdio` for local desktop tools, `SSE` over HTTP for remote microservices).
- - Hardening MCP tool security (input validation via Zod/Pydantic, permission scoping, prompt injection mitigation).
- - Debugging MCP JSON-RPC protocol messages or tool execution failures.
+ - Building an MCP server to expose tools, resources, or prompt templates to AI agents.
+ - Integrating third-party APIs or databases as MCP tools for LLM consumption.
+ - Implementing MCP client logic in an AI agent or chatbot.
+ - Securing MCP servers with OAuth 2.1 and permission scoping.
+ - Deploying MCP servers to edge/serverless environments.
- ### Core Protocol Architecture (MCP Primitives)
+ ### MCP v1.9+ Specification Overview
- ```
- +-------------------+ JSON-RPC 2.0 (stdio / SSE) +-------------------+
- | MCP Client | <=================================> | MCP Server |
- | (AI Agent / IDE) | | (Tools/Resources) |
- +-------------------+ +-------------------+
- ```
+ MCP standardizes how AI models interact with external tools and data. The 2026 specification (v1.9) introduces:
- 1. **Tools**: Executable functions exposed to the AI agent (`tools/list`, `tools/call`). Must return structured content arrays (text, images, embedded resources).
- 2. **Resources**: Passive data sources read by the LLM (`resources/list`, `resources/read`). Identified by URIs (e.g., `postgres://db/users`, `file:///logs/app.log`).
- 3. **Prompts**: Reusable prompt templates with parameter substitution (`prompts/list`, `prompts/get`).
- 4. **Transports**:
- - **`stdio`**: Standard Input/Output transport for local CLI scripts and desktop apps (zero network overhead).
- - **`SSE` (Server-Sent Events)**: HTTP-based transport for remote services, microservices, and containerized deployments.
+ | Feature | Description |
+ |---|---|
+ | **Streamable HTTP** | New bidirectional transport via HTTP streaming — replaces SSE for cloud deployments |
+ | **stdio** | Original transport for local/CLI tools — still recommended for local MCP |
+ | **OAuth 2.1** | Standard authorization flow for MCP servers requiring user consent |
+ | **Tool Annotations** | `readOnlyHint`, `destructiveHint`, `idempotentHint` for safer agent decisions |
+ | **Audio Content** | Support for audio data in tool responses |
+ | **Resource Links** | Resources can now link to external URIs |
- ---
+ ### Core MCP Concepts
- ### Implementation Examples
+ | Primitive | What It Is | Example |
+ |---|---|---|
+ | **Tool** | Executable function the LLM can call | `search_database`, `send_email` |
+ | **Resource** | Read-only data the LLM can read | File contents, DB records |
+ | **Prompt** | Reusable prompt templates | `code_review_prompt` |
+ | **Sampling** | Server requests LLM completion | Agent asks LLM to classify |
- #### TypeScript (`@modelcontextprotocol/sdk`)
+ ### Building an MCP Server (TypeScript)
+
+ #### 1. Setup with `@modelcontextprotocol/sdk`
```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
- import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { z } from 'zod';
const server = new McpServer({
- name: 'my-database-mcp',
+ name: 'my-api-server',
version: '1.0.0',
});
+ ```
- // Register an executable tool with strict Zod schema validation
+ #### 2. Define Tools with Zod Validation
+ ```typescript
server.tool(
- 'query-users',
+ 'search_products',
+ 'Search the product catalog by query and category',
{
- role: z.enum(['admin', 'user']),
- limit: z.number().min(1).max(100).default(10),
+ query: z.string().min(1).describe('Search query string'),
+ category: z.enum(['electronics', 'clothing', 'books']).optional(),
+ limit: z.number().int().min(1).max(50).default(10),
},
- async ({ role, limit }) => {
- const users = await db.query(`SELECT id, email FROM users WHERE role = $1 LIMIT $2`, [role, limit]);
+ {
+ readOnlyHint: true, // v1.9 annotation: this tool does not modify state
+ idempotentHint: true, // safe to call multiple times
+ },
+ async ({ query, category, limit }) => {
+ const results = await productDB.search({ query, category, limit });
return {
- content: [
- {
- type: 'text',
- text: JSON.stringify(users, null, 2),
- },
- ],
+ content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
};
}
);
+ ```
- // Connect via stdio transport
- const transport = new StdioServerTransport();
- await server.connect(transport);
+ #### 3. Expose Resources
+ ```typescript
+ server.resource(
+ 'company-docs',
+ 'docs://{path}',
+ { mimeType: 'text/markdown' },
+ async (uri) => {
+ const path = uri.pathname;
+ const content = await fs.readFile(`./docs${path}`, 'utf-8');
+ return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: content }] };
+ }
+ );
```
- #### Python (`mcp` / `FastMCP`)
- ```python
- from mcp.server.fastmcp import FastMCP
+ #### 4. Streamable HTTP Transport (v1.9 — Production Deployment)
+ ```typescript
+ import express from 'express';
- mcp = FastMCP("weather-service")
+ const app = express();
+ app.use(express.json());
- @mcp.tool()
- def get_temperature(city: str) -> str:
- """Fetch current temperature for a given city."""
- # Input parameter city is automatically validated
- return f"The current temperature in {city} is 24°C."
+ app.all('/mcp', async (req, res) => {
+ const transport = new StreamableHTTPServerTransport({
+ sessionIdGenerator: () => crypto.randomUUID(),
+ });
+ await server.connect(transport);
+ await transport.handleRequest(req, res, req.body);
+ });
- if __name__ == "__main__":
- mcp.run(transport="stdio")
+ app.listen(3000, () => console.log('MCP Server running on :3000'));
```
- ---
+ #### 5. OAuth 2.1 Authorization (Secure MCP)
+ For MCP servers requiring user consent (e.g., accessing user's GitHub repos):
+ ```typescript
+ import { ProxyOAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/providers/proxyOAuth.js';
- ### Security Guardrails & Best Practices
- - **Least Privilege**: Grant MCP tools access only to specific paths or read-only database roles.
- - **Never Execute Arbitrary Shell/SQL**: Avoid exposing wildcard shell commands (`exec(cmd)`) or raw unparameterized SQL (`db.query(raw_string)`).
- - **Sanitize Input**: Validate all tool inputs against strict Zod/Pydantic schemas to prevent prompt injection payload execution.
- - **User Confirmation**: Require explicit human approval for destructive operations (`DELETE`, `DROP`, external payment triggers).
+ const authProvider = new ProxyOAuthServerProvider({
+ endpoints: {
+ authorizationUrl: 'https://github.com/login/oauth/authorize',
+ tokenUrl: 'https://github.com/login/oauth/access_token',
+ },
+ clientId: process.env.GITHUB_CLIENT_ID!,
+ clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ scopes: ['repo', 'read:user'],
+ });
+ server.setAuthProvider(authProvider);
+ ```
+
+ ### Security Hardening
+
+ - **Validate ALL inputs**: Every tool parameter must be validated with Zod before execution. Never trust LLM-generated inputs directly.
+ - **Principle of Least Privilege**: Each tool should only request the minimum permissions needed.
+ - **Rate Limiting**: Implement per-session rate limits to prevent prompt injection loops.
+ - **Sanitize Outputs**: Never return raw database records with sensitive fields (passwords, API keys). Always filter/select only what's needed.
+ - **Audit Logging**: Log every tool call with session ID, tool name, parameters, and result status.
+ - **Tool Annotations**: Use `destructiveHint: true` for tools that modify or delete data — agents should ask for human confirmation before calling these.
+
+ ### Multi-Server Orchestration
+ When building AI apps with multiple MCP servers:
+ ```typescript
+ // Client connecting to multiple MCP servers
+ const client = new McpClient({ name: 'my-agent', version: '1.0.0' });
+
+ // Connect to multiple specialized servers
+ await client.connect(new StdioTransport({ command: 'node', args: ['file-server.js'] }));
+ await client.connect(new StreamableHTTPTransport({ url: 'https://api.mydb.com/mcp' }));
+
+ // List all available tools across servers
+ const { tools } = await client.listTools();
+ ```
+
---
<a name="bahasa-indonesia"></a>
## Bahasa Indonesia
### Deskripsi
- Panduan arsitektur tingkat produksi untuk merancang, membangun, menguji, dan mengamankan server **Model Context Protocol (MCP)**. MCP adalah standar protokol terbuka yang menyelaraskan cara agen Kecerdasan Buatan (AI) (seperti Claude Desktop, Antigravity, Cursor, Windsurf, dan aplikasi LLM kustom) menemukan dan mengeksekusi *tools*, membaca *resources* terstruktur, dan memuat *prompt templates* melalui transport JSON-RPC 2.0.
+ Panduan ahli untuk merancang, membangun, dan mengamankan server **Model Context Protocol (MCP)** dan integrasi klien. Mencakup spesifikasi MCP v1.9+ (termasuk transport Streamable HTTP baru), desain tool/resource/prompt, validasi Zod, otorisasi OAuth 2.1, dan pola orkestrasi multi-server untuk aplikasi AI produksi.
### Kondisi Pemicu
- - Merancang atau mengimplementasikan MCP Server kustom dalam **TypeScript**, **Python**, atau **Go**.
- - Mengekspos database, API, alat CLI lokal, atau infrastruktur cloud ke agen AI.
- - Mengonfigurasi transport MCP (`stdio` untuk alat desktop lokal, `SSE` melalui HTTP untuk microservice remote).
- - Mengamankan alat MCP (validasi input via Zod/Pydantic, pembatasan hak akses, mitigasi *prompt injection*).
- - Men-debug pesan protokol JSON-RPC MCP atau kegagalan eksekusi alat.
+ - Membangun MCP server untuk mengekspos tool, resource, atau prompt template ke agen AI.
+ - Mengintegrasikan API pihak ketiga atau database sebagai MCP tool untuk konsumsi LLM.
+ - Mengimplementasikan logika klien MCP dalam agen AI atau chatbot.
+ - Mengamankan MCP server dengan OAuth 2.1 dan pembatasan izin.
+ - Men-deploy MCP server ke lingkungan edge/serverless.
- ### Arsitektur Inti Protokol (MCP Primitives)
+ ### Ringkasan Spesifikasi MCP v1.9+
- 1. **Tools**: Fungsi eksekusi yang diekspos ke agen AI (`tools/list`, `tools/call`). Wajib mengembalikan array konten terstruktur (teks, gambar, resource tersemat).
- 2. **Resources**: Sumber data pasif yang dibaca oleh LLM (`resources/list`, `resources/read`). Diidentifikasi melalui URI (misal: `postgres://db/users`, `file:///logs/app.log`).
- 3. **Prompts**: Template prompt yang dapat digunakan kembali dengan substitusi parameter (`prompts/list`, `prompts/get`).
- 4. **Transports**:
- - **`stdio`**: Transport Standard Input/Output untuk skrip CLI dan aplikasi desktop lokal (tanpa overhead jaringan).
- - **`SSE` (Server-Sent Events)**: Transport berbasis HTTP untuk layanan remote dan deployment dalam container.
+ MCP menstandarisasi cara model AI berinteraksi dengan tool dan data eksternal. Spesifikasi 2026 (v1.9) memperkenalkan:
+ - **Streamable HTTP**: Transport dua arah baru via HTTP streaming — menggantikan SSE untuk deployment cloud.
+ - **Tool Annotations**: `readOnlyHint`, `destructiveHint`, `idempotentHint` untuk keputusan agen yang lebih aman.
+ - **OAuth 2.1**: Alur otorisasi standar untuk MCP server yang memerlukan izin pengguna.
- ---
+ ### Membangun MCP Server (TypeScript)
- ### Panduan Keamanan & Praktik Terbaik
- - **Hak Akses Minimum (Least Privilege)**: Berikan akses alat MCP hanya ke direktori yang spesifik atau role database *read-only*.
- - **Jangan Pernah Eksekusi Shell/SQL Bebas**: Hindari mengekspos perintah shell bebas (`exec(cmd)`) atau kueri SQL mentah tanpa parameterization.
- - **Sanitasi Input**: Validasi semua parameter masuk menggunakan skema Zod/Pydantic yang ketat untuk mencegah serangan *prompt injection*.
- - **Konfirmasi Pengguna**: Wajibkan persetujuan manusia secara eksplisit untuk operasi destruktif (`DELETE`, `DROP`, pemicu pembayaran eksternal).
+ Gunakan `@modelcontextprotocol/sdk` untuk TypeScript. Definisikan tool dengan validasi Zod yang ketat, tambahkan anotasi v1.9 (`readOnlyHint`, `destructiveHint`), dan gunakan Streamable HTTP transport untuk deployment cloud produksi.
+
+ ### Keamanan MCP
+
+ - **Validasi SEMUA input**: Setiap parameter tool harus divalidasi dengan Zod sebelum eksekusi.
+ - **Prinsip Least Privilege**: Setiap tool hanya boleh meminta izin minimum yang diperlukan.
+ - **Rate Limiting**: Batasi panggilan per sesi untuk mencegah loop prompt injection.
+ - **Sanitasi Output**: Jangan pernah mengembalikan field sensitif (password, API key).
+ - **Audit Logging**: Catat setiap panggilan tool dengan session ID, nama tool, parameter, dan status hasil.
+ - **Anotasi Tool**: Gunakan `destructiveHint: true` untuk tool yang memodifikasi/menghapus data — agen harus meminta konfirmasi manusia sebelum memanggilnya.
+
+ ### Orkestrasi Multi-Server
+ Klien MCP dapat terhubung ke beberapa server sekaligus, menyatukan semua tool dari server yang berbeda menjadi satu daftar yang tersedia untuk agen.