若你已有 Python 或 TypeScript 基礎，卻卡在「如何讓 Claude、GPT 或 Cursor 安全調用自家 API、資料庫與知識庫」，本文提供從 Hello World 到生產部署的完整 MCP Server 開發路徑：含協議原理、Tools/Resources/Prompts 三大原語、HTTP+SSE 遠端傳輸、MCP Inspector 調試、Docker 部署、知識庫實戰專案，以及五步 Mac 雲 launchd 7×24 常駐 Runbook與承載環境決策矩陣。

1. MCP 協議原理與三層架構

Model Context Protocol（MCP）由 Anthropic 於 2024 年 11 月開源，定義 AI Host（如 Cursor、Claude Desktop）與外部工具/資料之間的統一 JSON-RPC 2.0 通信規範。截至 2026 年，OpenAI、Google Gemini、Microsoft 均已採納，生態已有超過 10,000 個公開 MCP Server。

┌─────────────────────────────────┐
│  Host（Cursor / Claude Desktop） │
│  ┌───────────────────────────┐  │
│  │  MCP Client（1:1 會話）    │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘
             ↕ JSON-RPC 2.0
┌─────────────────────────────────┐
│  MCP Server（你正在開發的）       │
│  Tools │ Resources │ Prompts     │
└─────────────────────────────────┘
             ↕
┌─────────────────────────────────┐
│  外部系統（API、DB、檔案、向量庫）│
└─────────────────────────────────┘

Server 需實作三類能力：tools/list + tools/call（可執行操作）、resources/list + resources/read（唯讀上下文）、prompts/list + prompts/get（預置提示模板）。傳輸層常見 STDIO（本地子進程）與 HTTP+SSE（遠端共享）。

2. 三大開發痛點

工具定義碎片化。 若為每個 AI 客戶端硬編碼 Function Calling Schema，換 Cursor → Claude Desktop 就要重寫；MCP 用 tools/list 運行時自描述，寫一次到處跑。
本地開發與生產脫節。 筆電上 STDIO 調通後，合蓋即斷；Docker on Linux 缺少 Apple 工具鏈，排障成本陡增。
安全與可觀測性缺口。 約 1,000 個公開 MCP Server 處於未授權暴露狀態；生產環境必須集中管理 Token、記錄 tools/call 延遲基線。

3. 環境準備

本文提供 TypeScript 與 Python 雙路徑，擇一即可。

TypeScript 路徑

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
npx tsc --init

Python 路徑

mkdir my-mcp-server && cd my-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx

建議 Node.js 20+ 或 Python 3.10+；Mac 開發者可直接在本地驗證，生產常駐見第 10 節 Runbook。

4. Hello World：第一個 MCP Server

以下 TypeScript 範例建立 STDIO Server，暴露一個 ping 工具：

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: "hello-mcp", version: "1.0.0" });

server.tool("ping", "Health check", { message: z.string().optional() },
  async ({ message }) => ({
    content: [{ type: "text", text: `pong: ${message ?? "ok"}` }]
  })
);

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

執行 npx tsx src/index.ts，Server 將在 STDIO 上監聽 JSON-RPC 請求。Python 等價寫法使用 mcp.server.Server + stdio_server()，邏輯相同。

5. Tools 開發：五個實戰工具

生產級 Server 通常暴露 3–8 個高價值工具。以下五例覆蓋常見場景：

工具名	用途	關鍵參數
`query_database`	唯讀 SQL 查詢	`sql: string`
`search_docs`	全文檢索知識庫	`query: string, limit?: number`
`create_ticket`	寫入工單系統	`title, body, priority`
`fetch_weather`	呼叫外部 REST API	`city: string`
`run_script`	沙箱執行腳本	`lang, code`（需白名單）

每個工具必須附 JSON Schema 參數描述與副作用說明（read-only / destructive），讓 Agent 在 tools/list 時自主選型。示例 search_docs：

server.tool("search_docs",
  "Search internal knowledge base (read-only)",
  { query: z.string(), limit: z.number().int().min(1).max(20).default(5) },
  async ({ query, limit }) => {
    const hits = await vectorStore.search(query, limit);
    return { content: [{ type: "text", text: JSON.stringify(hits, null, 2) }] };
  }
);

6. Resources：唯讀資源暴露

Resources 適合暴露配置檔、Schema 定義、API 規格等只讀上下文，Agent 透過 resources/read 按需拉取，避免塞爆 Prompt。

server.resource("config://app/settings", "Application settings JSON",
  async (uri) => ({
    contents: [{ uri: uri.href, mimeType: "application/json",
      text: await fs.readFile("config/settings.json", "utf8") }]
  })
);

URI 建議用自訂 scheme（如 kb://、db://）命名空間，便於 Client 快取與權限分級。

7. Prompts：可重用提示模板

Prompts 將團隊最佳實踐封裝為可發現模板，例如「程式碼審查 Checklist」或「Incident 回報格式」：

server.prompt("code-review", "Structured code review prompt",
  { language: z.string(), focus: z.string().optional() },
  ({ language, focus }) => ({
    messages: [{
      role: "user",
      content: { type: "text",
        text: `Review this ${language} code. Focus: ${focus ?? "security, perf, readability"}.` }
    }]
  })
);

8. HTTP+SSE 遠端傳輸

團隊共享或雲部署時，將 STDIO 換為 Streamable HTTP（2025 規範）或 HTTP+SSE：

import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
// Express/Fastify 路由：GET /sse 建立 SSE，POST /message 收 JSON-RPC
app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/message", res);
  await server.connect(transport);
});

傳輸	適用	優點	注意
STDIO	Cursor / Claude Desktop 本地	零依賴、隔離好	需子進程常駐
HTTP+SSE	遠端團隊、多 Client 共享	跨網路、可水平擴展	需 session affinity

9. 調試與測試

MCP Inspector：npx @modelcontextprotocol/inspector node dist/index.js，圖形化測 tools/list 與 tools/call。
Cursor 配置：在專案或全域 .cursor/mcp.json 註冊 Server 命令與環境變數。
日誌分層：stderr 輸出結構化日誌（禁止污染 STDIO JSON-RPC 通道）；記錄每次 tools/call 耗時。
單元測試：對工具 handler 做 mock 測試，避免每次調試都啟動完整 Host。

{
  "mcpServers": {
    "my-kb-server": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/dist/index.js"],
      "env": { "KB_INDEX_PATH": "/data/kb.index" }
    }
  }
}

10. 生產部署與五步 Runbook

承載環境決策矩陣

承載	STDIO	7×24	原生 macOS	適合
MacBook 本地	✅	❌ 合蓋斷線	✅	個人驗證
Linux VPS + Docker	⚠️	✅	❌	純 HTTP Server
VPSMAC M4 Mac 雲	✅ launchd	✅	✅ 裸機 SSH	Cursor + MCP 同機常駐

五步 Runbook

選傳輸層：IDE 整合用 STDIO；團隊共享選 HTTP+SSE。
建置與打包：npm run build 或 pip freeze 鎖定依賴版本。
Cursor / Claude 配置：寫入 mcp.json，驗證 tools/list 返回預期 Schema。
Docker（可選）：HTTP 模式可容器化；STDIO 模式建議裸機 launchd。
launchd 常駐：在 Mac 雲節點註冊 plist，設定 SoftResourceLimits 與日誌路徑。

# Dockerfile（HTTP 模式示例）
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js", "--transport", "http", "--port", "3000"]

11. 知識庫 MCP 實戰專案

將內部 Markdown/Wiki 索引為向量庫，暴露三個能力：

Tool search_kb：語意檢索 Top-K 片段，返回引用來源。
Resource kb://manifest：文檔目錄與更新時間，供 Agent 規劃查詢路徑。
Prompt answer-with-citations：強制回答附 [doc_id:line] 引用格式。

索引管線：cron 增量掃描 → embedding（本地 Ollama 或 API）→ 寫入 LanceDB/SQLite-VSS。在 Mac 雲節點上，可與 OpenClaw Gateway 同機部署，Agent 7×24 調用知識庫而無需筆電在線。詳見站內 MCP 協議全景。

12. 2026 生態展望

AAIF 治理：MCP 已移交 Linux Foundation Agentic AI Foundation，成為行業公共基礎設施。
OAuth 2.1 標準化：遠端 Server 身份驗證納入 2026 路線圖，企業 SSO 整合加速。
註冊表缺口：統一 MCP Server 發現（類 DNS）仍在醞釀，短期仍靠配置與私有目錄。
與 A2A 互補：MCP 管垂直工具集成；Google A2A 管 Agent 橫向編排。

13. 可引用技術要點（2026）

協議核心：JSON-RPC 2.0 上的 tools/list、tools/call、resources/read、prompts/get 四原語。
生態規模：公開 MCP Server 超過 10,000 個；四大模型廠商（Anthropic/OpenAI/Google/Microsoft）均已採納。
成本效益：標準化 MCP 接口後，企業 AI 集成開發成本降幅 38–55%（行業調研均值）。
安全基線：生產 Server 必須啟用鉴权、參數校驗與 tools/call 審計日誌；禁止將 STDIO Server 直接暴露公網。

14. 結語

從 Hello World 到知識庫實戰，MCP Server 的本質是把「AI 能發現並正確調用什麼」標準化——寫一次，Cursor、Claude Desktop、VS Code 均可復用。本地筆電適合驗證，但合蓋斷線、環境漂移與無 launchd 託管會讓 STDIO 子進程在生產中不可靠；Linux Docker 雖可跑 HTTP 模式，卻增加排障層級且缺少 Apple 工具鏈。

若你需要 Cursor、OpenClaw 或 Claude Desktop 與 MCP Server 長期同機 7×24 常駐、原生 macOS 與 launchd 託管，租賃 VPSMAC 的 M4 Mac 雲節點通常是更省心、更適合 AI 自動化生產環境的選擇——工具層寫一次，模型隨意換，節點始終在線。

從 0 開發一個 MCP Server：手把手教你構建 AI 工具調用能力（2026）

目錄