從零開發 MCP Server：2026 手把手建構 AI 工具呼叫能力

大模型再聰明，沒有「手腳」也查不了資料庫、調不了 API、讀不了你的本地筆記。Model Context Protocol（MCP） 用 JSON-RPC 把 AI 客戶端與外部能力標準化對接——2026 年生態已超 13,000 個 Server，OpenAI、Google、Microsoft 全面支援。痛點：Function Calling 各寫一套、換模型就要推倒重來。結論：讀完本文你能獨立開發、除錯並部署正式環境可用的 MCP Server。結構：協定原理 → 環境建置 → Hello World → Tools/Resources/Prompts → HTTP 遠端 → 除錯測試 → Docker 部署 → 個人知識庫實戰 → 生態展望。

1. 什麼是 MCP？先搞懂協定再寫程式

1.1 MCP 的誕生背景

工具呼叫能力經歷了三代演進：Function Calling（OpenAI 私有格式）→ Plugins（ChatGPT 外掛生態，已式微）→ MCP（開放標準）。Anthropic 於 2024 年 11 月開源 MCP，核心動機是：每換一個 AI 客戶端就要重寫一遍工具整合，形成 N×M 爆炸。MCP 解決的是標準化 AI 與外部工具的通訊協定——寫一次 Server，Cursor、Claude Desktop、VS Code 都能用。2026 年治理權已移交 Linux Foundation 旗下 AAIF。

1.2 MCP 協定架構概覽

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (你要開發的部分)    │
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (工具呼叫)    (資源讀取)    (提示詞模板)

Client：AI 模型側宿主（Claude Desktop、Cursor、自訂 Agent）。Server：你開發的能力提供方。三大核心能力：Tools 是 AI 可呼叫的函式（搜尋、計算、SQL）；Resources 是 AI 可讀取的資料（檔案、設定、URL）；Prompts 是預定義提示詞模板，支援參數注入。

1.3 MCP 通訊機制

底層基於 JSON-RPC 2.0。傳輸方式：stdio（本地子程序，零網路設定）與 Streamable HTTP（2025-06-18 規範取代舊版 HTTP+SSE，適合遠端/多客戶端）。生命週期：初始化握手 → 能力協商（tools/list）→ 請求/回應 → 關閉。⚠️ 本地 stdio 模式禁止向 stdout 列印非協定日誌，否則 JSON-RPC 解析會失敗。

1.4 MCP vs 其他方案對比

對比維度	MCP	OpenAI Function Calling	LangChain Tools
標準化程度	開放協定標準	廠商私有	框架綁定
傳輸方式	stdio / Streamable HTTP	HTTP	HTTP
跨模型支援	是	否	部分
資源/提示詞	原生支援	不支援	不支援
生態工具	13,000+ Server（2026）	成熟	成熟

2. 開發環境準備

2.1 選擇開發語言

Python（推薦新手）：官方 SDK mcp + FastMCP 裝飾器，簡潔易上手。TypeScript（推薦前端/全端）：@modelcontextprotocol/sdk + Zod 校驗，npm 下載量已超 150M。本文以 Python 為主，TypeScript 做對照說明。

2.2 環境建置

# Python 環境
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

# TypeScript 環境（對照）
npm init -y
npm install @modelcontextprotocol/sdk zod

2.3 專案結構設計

my-mcp-server/
├── server.py            # 主服務入口
├── tools/               # 工具模組
│   ├── calculator.py
│   └── web_search.py
├── resources/           # 資源模組
│   └── file_reader.py
├── prompts/             # 提示詞模板
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

2.4 除錯工具安裝

1）MCP Inspector：npx @modelcontextprotocol/inspector python server.py，瀏覽器 UI 在 localhost:6274 除錯 Tools/Resources/Prompts。2）Claude Desktop：編輯 ~/Library/Application Support/Claude/claude_desktop_config.json。3）Cursor：Settings → MCP → 新增 mcpServers 設定。詳見本站 MCP 協定深度解讀。

3. 第一個 MCP Server：Hello World

3.1 最簡單的 MCP Server

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """向指定的人打招呼"""
    return f"Hello, {name}! 這是你的第一個 MCP 工具。"

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

3.2 執行與驗證

python server.py
# 或使用 MCP Inspector 除錯
npx @modelcontextprotocol/inspector python server.py

3.3 在 Cursor / Claude Desktop 中接入

// claude_desktop_config.json 或 Cursor MCP 設定
{
  "mcpServers": {
    "my-first-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

⚠️ 必須使用絕對路徑指向 Python 直譯器與腳本。重啟客戶端後，在對話中應能看到 say_hello 工具出現在上下文中。

4. Tools：開發可被 AI 呼叫的工具

4.1 工具的基本結構

函式簽名即文件：參數型別、回傳型別、docstring 會被 SDK 自動轉為 JSON Schema 供 LLM 理解。命名規範：小寫+底線，語意清晰（web_search 優於 ws）。錯誤處理：回傳結構化錯誤字串優於直接拋未捕獲例外，避免整個 Server 崩潰。

4.2 輸入參數型別支援

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="搜尋關鍵字")
    max_results: int = Field(default=5, description="最多回傳結果數")
    language: str = Field(default="zh", description="結果語言")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """執行網路搜尋，回傳相關結果列表"""
  # 實作搜尋邏輯
    return [{"title": "範例", "url": "https://example.com"}]

4.3 實戰案例：5 個實用工具

工具	用途	關鍵實作
計算器	數學表達式求值	`eval` 需沙箱或 `ast` 安全解析
檔案讀寫	讀/寫本地檔案	限制允許目錄，防路徑穿越
HTTP 請求	呼叫外部 API	`httpx` + 逾時 30s
資料庫查詢	執行唯讀 SQL	參數化查詢，禁 DDL
時間工具	目前時間/時區轉換	`zoneinfo` 標準函式庫

4.4 非同步工具開發

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """取得指定 URL 的內容"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        return response.text[:10000]  # 截斷防 token 爆炸

4.5 工具錯誤處理最佳實踐

1）結構化錯誤：回傳 {"error": "...", "code": "TIMEOUT"} 字串。2）逾時：所有 I/O 操作設 30s 上限。3）權限校驗：在 Tool 層白名單目錄/API，不要依賴 LLM「自覺」。

5. Resources：讓 AI 讀取動態內容

5.1 Resource 與 Tool 的區別

Resource 是資料提供者（唯讀為主），Tool 是動作執行者。URI 定址：file://、http://、custom:// 自訂 scheme。

5.2 靜態資源 vs 動態資源

import json

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    """回傳應用設定"""
    return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """根據使用者 ID 回傳使用者資料"""
    return json.dumps({"user_id": user_id, "name": "Demo"})

5.3 資源型別

文字資源（text/plain、application/json）、二進位資源（圖片/PDF，回傳 base64）、串流資源（即時行情，需 Streamable HTTP）。

5.4 實戰：檔案系統資源伺服器

列出目錄、讀取檔案內容、可選訂閱檔案變化（resources/subscribe）。正式環境務必限制根目錄，參考官方 mcp-server-filesystem 的 allowlist 設計。

6. Prompts：定義可複用的提示詞模板

6.1 什麼是 MCP Prompt？

預定義提示詞片段，AI 可直接複用；支援動態參數注入；提升團隊 Prompt 一致性與可維護性。與 Cursor Agent Skills 互補：MCP Prompt = 協定層模板，Skill = 操作手冊。

6.2 建立提示詞模板

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """程式碼審查提示詞模板"""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"""請對以下 {language} 程式碼進行審查：
1. 程式碼品質和可讀性
2. 潛在 Bug 和安全隱患
3. 效能優化建議

```{language}
{code}
```"""
            )
        )
    ]

6.3 多輪對話提示詞

可定義包含 user 和 assistant 的多輪模板。場景：面試模擬（assistant 扮演面試官）、程式碼除錯助手（assistant 先問澄清問題）。

7. 進階：HTTP 傳輸模式（遠端 MCP Server）

7.1 stdio vs Streamable HTTP

特性	stdio	Streamable HTTP
部署方式	本地程序	遠端伺服器
延遲	極低（<5ms）	依賴網路（50–200ms）
多客戶端	不支援	支援
適用場景	本地工具、IDE 外掛	SaaS/團隊共享/7×24

⚠️ 舊版 HTTP+SSE 已在 2025-06-18 規範中廢棄，新專案請用 Streamable HTTP。

7.2 實作 HTTP 傳輸

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-server")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

正式部署可用 uvicorn/gunicorn 反向代理。Serverless（Cloud Run/Lambda）需 stateless_http=True，因記憶體 session 會在冷啟動時遺失。

7.3 認證與安全

Bearer Token 認證、API Key 中介軟體、CORS 白名單、請求頻率限制（建議 100 req/min/IP）。本地開發綁定 127.0.0.1，禁止 0.0.0.0 無認證暴露。2026 年已披露 30+ MCP 相關 CVE，含 CVSS 9.6 的 mcp-remote RCE。

8. 除錯與測試

8.1 使用 MCP Inspector 除錯

啟動後可在 UI 中：列出 Tools → 手動呼叫 → 查看 JSON-RPC 原始報文 → 模擬逾時/錯誤場景。比直接連 LLM 除錯效率高 10×。

8.2 撰寫單元測試

import pytest
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(
        command="python", args=["server.py"]
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("calculate", {"expression": "2 + 2"})
            assert "4" in result.content[0].text

8.3 常見錯誤排查

錯誤	原因	解決方案
工具未出現在 AI 中	設定路徑錯誤	檢查 config.json 絕對路徑
JSON 序列化失敗	回傳型別不支援	轉為 str 或 dict
逾時斷開	工具執行太慢	非同步 + 30s 逾時
權限拒絕	檔案路徑受限	設定 allowlist 目錄

9. 正式部署

9.1 Docker 容器化

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

9.2 部署到雲端服務

Railway / Render：一鍵部署，適合個人專案（月費約 $5–20）。AWS Lambda / Google Cloud Run：Serverless，按呼叫計費。自建 VPS：Nginx 反向代理 + Let's Encrypt + systemd/launchd 保活。

9.3 監控與可觀測性

結構化日誌（JSON Lines）、Prometheus 指標（mcp_tool_calls_total）、Sentry 錯誤告警、/health 健康檢查端點。建議 P99 延遲告警閾值 5s。

9.4 版本管理與相容性

在握手時宣告 MCP 協定版本；工具升級保持向後相容（新增可選參數而非改必填項）；利用 capabilities 協商避免 Client 呼叫不存在的 Tool。

10. 實戰專案：個人知識庫 MCP Server

10.1 專案需求

讓 AI 能搜尋本地 Markdown 筆記、語意檢索、建立/更新筆記。在 Cursor 中問：「我上週記錄了什麼關於 MCP 的筆記？」

10.2 技術選型

元件	選型	理由
向量資料庫	ChromaDB / Qdrant	本地輕量、零維運
嵌入模型	text-embedding-3-small	1536 維、成本低
檔案監聽	watchfiles	筆記變更自動重索引

10.3 核心程式實作

四個模組：index_notes 工具（掃描目錄建索引）、semantic_search 工具（向量檢索 Top-K）、write_note 工具（建立/追加 Markdown）、notes://{path} 資源（直接讀取單檔案）。索引約 1000 篇筆記耗時 2–5 分鐘（M4 Pro）。

10.4 效果演示

使用者在 Cursor 輸入：「我上週關於 MCP 部署的筆記說了什麼？」→ Agent 呼叫 semantic_search(query="MCP 部署", days=7) → 回傳 3 條相關片段（相似度 0.82–0.91）→ LLM 綜合回答並引用原文。全程無需把整庫筆記塞進 Context Window。

11. MCP 生態與未來展望

11.1 優質 MCP Server 推薦

mcp-server-filesystem（檔案系統）、mcp-server-github（儲存庫操作）、mcp-server-brave-search（網路搜尋）、mcp-server-postgres（資料庫）、mcp-server-slack（訊息）。官方註冊表已追蹤 13,000+ Server。

11.2 MCP 生態趨勢（2026）

四大廠商全面支援；MCP Marketplace 興起；企業級 OAuth 2.1 身分驗證列入路線圖；與 Google A2A 協定互補（MCP = 垂直工具層，A2A = Agent 橫向編排）。

11.3 下一步學習路徑

① 精讀 modelcontextprotocol.io 規範；② 發布第一個公開 MCP Server；③ 探索 MCP + Agent 組合；④ 貢獻開源生態（Python/TS SDK）。

12. 五步落地清單

Step 1 — 用 FastMCP 寫 Hello World，Inspector 驗證。Step 2 — 註冊 3 個業務 Tool + 1 個 Resource。Step 3 — 接入 Cursor / Claude Desktop（絕對路徑設定）。Step 4 — 按需切 Streamable HTTP 遠端部署。Step 5 — Docker + 監控 + 安全稽核上線。

13. 可引用數字

指標	數值
MCP Server 生態（2026）	13,000+
18 個月成長倍數	7.8×（1,200 → 9,400+）
TS SDK 累計下載	150M+
2026 年 MCP 相關 CVE	30+
推薦 Tool I/O 逾時	30s
知識庫索引（1000 篇）	2–5 min（M4 Pro）

14. 深度案例：從本機 stdio 到 Mac 遠端算力節點

某 AI 工程師在 MacBook Air 上同時跑 Cursor + 5 個 stdio MCP Server（filesystem、postgres、brave-search、自訂知識庫、瀏覽器工具）。統一記憶體 24GB 常駐占用 19GB，筆電發熱降頻、合蓋即斷連。遷移方案：本機僅保留 Cursor Host；5 個 Server 以 Streamable HTTP 部署到遠端 Mac mini（64GB 統一記憶體），launchd 保活；本機透過 url: http://node.macgpu.local:8000/mcp 連線。工具呼叫 P99 延遲從本地 180ms 升至 95ms（遠端節點無降頻）——反而更穩。

Windows/Linux VPS 能跑 MCP Server，但在與 Xcode、ComfyUI、Final Cut 並行的圖形/多媒體 + AI 工具鏈場景，macOS 仍更順暢。本地 stdio 適合開發與驗證；7×24 正式常駐更適合遠端 Apple Silicon 節點：統一記憶體留給並發 Tool 呼叫，筆電只做編排。

若你需要穩定、可租用的環境託管 MCP Server 叢集與 Agent Gateway，可考慮 MACGPU 遠端 Mac 節點：7×24 常駐、HTTP 反向代理已配、統一記憶體不被多子程序占滿——從「能跑」到「穩跑」只差一個節點。