協定原理 · FastMCP 實戰 · Tools/Resources/Prompts · HTTP 遠端部署 · 知識庫專案
為什麼 AI 模型「不夠聰明」？因為它無法存取外部工具與即時資料。若你希望 Claude/GPT 能查資料庫、調 API、讀寫檔案，MCP（Model Context Protocol） 正是標準化答案。本文面向有 Python 或 TypeScript 基礎的後端 / AI 開發者：從協定原理到環境搭建，涵蓋 Tools、Resources、Prompts 註冊、MCP Inspector 除錯、HTTP+SSE 遠端部署與個人知識庫實戰專案，讀完後你將能獨立開發並部署生產可用的 MCP Server。
大模型工具調用能力經歷了 Function Calling → Plugins → MCP 的演進。Anthropic 設計 MCP 的核心動機，是用開放協定標準化 AI 與外部工具的通訊——讓「寫一次 Server、多 Client 複用」成為現實。
MCP Client（Claude Desktop、Cursor、自訂客戶端）與 MCP Server（你開發的部分）透過 JSON-RPC 2.0 通訊。Server 向下對接三類核心能力：Tools（可呼叫函式，如搜尋、計算、資料庫查詢）、Resources（可讀取資源，如檔案、URL、資料流）、Prompts（預定義提示詞範本）。
傳輸方式分兩種：stdio（本地子程序，延遲極低）與 HTTP + SSE（遠端伺服器，支援多客戶端）。生命週期為：初始化握手 → 能力協商 → 請求/回應 → 關閉。
模型缺乏即時資料：訓練截止導致無法回答「今天股價」或「最新工單狀態」，必須接外部 API。
各廠商工具格式不統一：ChatGPT Plugins、OpenAI Function Calling、Claude Tool Use 各自為政，換模型要重寫整合層。
IDE 無法複用工具資產：Cursor、VS Code、Claude Desktop 各有一套接入方式，團隊沉澱的工具無法跨產品遷移。
Agent 框架綁定：LangChain Tools 無法直接給 CrewAI 用，編排資產鎖死在框架而非團隊。
N×M 維護成本：N 個模型 × M 個外部系統 = 指數級客製化整合，MCP 將其收斂為「一次 Server、處處可用」。
| 對比維度 | MCP | OpenAI Function Calling | LangChain Tools |
|---|---|---|---|
| 標準化程度 | 開放協定標準 | 廠商私有 | 框架綁定 |
| 傳輸方式 | stdio / HTTP | HTTP | HTTP |
| 跨模型支援 | 是 | 否 | 部分 |
| Resources / Prompts | 原生支援 | 不支援 | 不支援 |
| 生態工具 | 快速成長（10000+ Server） | 成熟 | 成熟 |
讀完本節再動手寫程式碼：MCP 不是又一個 SDK，而是 AI 工具化的標準協定——掌握它，是 2026 年 AI 工程師的核心競爭力。
Python（官方 SDK mcp + FastMCP）推薦新手；TypeScript（@modelcontextprotocol/sdk）適合前端 / 全端。本文以 Python 為主，TypeScript 做對照說明。
python -m venv .venv source .venv/bin/activate pip install mcp npm init -y npm install @modelcontextprotocol/sdk
推薦專案結構：
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
除錯工具三件套：MCP Inspector（官方 UI，npx @modelcontextprotocol/inspector）、Claude Desktop 本地聯調（claude_desktop_config.json）、Cursor MCP 設定（Settings → MCP Servers）。官方文件見 modelcontextprotocol.io。
以下六步 Runbook 幫你在 30 分鐘內跑通第一個可被 AI 呼叫的工具。
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()
建立虛擬環境並安裝 mcp：pip install mcp，確認 Python ≥ 3.10。
撰寫 server.py：用 @mcp.tool() 裝飾器註冊 say_hello，docstring 即工具描述。
Inspector 除錯：npx @modelcontextprotocol/inspector python server.py，在 UI 中測試 tools/list 與 tools/call。
Cursor 設定：在 MCP 設定中添加 {"command":"python","args":["/path/to/server.py"]}，重啟後確認工具出現在 Agent 上下文。
Claude Desktop 設定：編輯 ~/Library/Application Support/Claude/claude_desktop_config.json，格式與 Cursor 相同。
驗證呼叫：在 Cursor 中輸入「用 say_hello 向 VpsMesh 打招呼」，確認 Agent 自動選擇工具並回傳結果。
提示：函式簽名即文件——參數類型、回傳類型、docstring 會直接暴露給 LLM，決定 Agent 能否正確選用你的工具。
工具是 MCP Server 的核心。命名規範建議動詞開頭（search_web、query_database）；複雜參數用 Pydantic 建模：
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]:
"""執行網路搜尋，回傳相關結果清單"""
...
eval 裸呼叫。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
錯誤處理最佳實務：對可預期失敗回傳結構化錯誤資訊（含 error_code 與 message）；網路 IO 必須設逾時；寫入操作前做權限校驗與稽核記錄。
Resource 與 Tool 的區別：Resource 是資料提供者（唯讀），Tool 是動作執行者。透過 URI 尋址：file://、http://、custom://。
@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:
user = db.query_user(user_id)
return json.dumps(user)
資源類型涵蓋文字（text/plain、application/json）、二進位（圖片、PDF）與串流即時資料。檔案系統資源伺服器可實作：列出目錄、讀取檔案、監聽變化（資源訂閱）。
MCP Prompt 是預定義片段，支援動態參數注入，提升一致性與可維護性。可定義包含 user 與 assistant 的多輪範本，適用於程式碼審查、面試模擬、除錯助手等場景。
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} 程式碼進行審查，重點關注品質、Bug 與效能。\n```{language}\n{code}\n```"
)
)
]
| 特性 | stdio | HTTP + SSE |
|---|---|---|
| 部署方式 | 本地程序 | 遠端伺服器 |
| 延遲 | 極低 | 相依網路與頻寬 |
| 多客戶端 | 不支援 | 支援 |
| 適用場景 | 本地工具 | SaaS / 團隊共享 |
mcp = FastMCP("remote-server", transport="streamable-http")
if __name__ == "__main__":
mcp.run(host="0.0.0.0", port=8000)
遠端部署安全要點：Bearer Token 驗證、API Key 校驗中介軟體、CORS 設定、請求頻率限制。生產環境禁止把金鑰寫進 tool schema。
Inspector 可測試 Tools 呼叫、查看 JSON-RPC 記錄、模擬錯誤場景。單元測試用官方 Client SDK 啟動 stdio 子程序：
@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 result.content[0].text == "4"
| 錯誤 | 原因 | 解決方案 |
|---|---|---|
| 工具未出現在 AI 中 | 設定路徑錯誤 | 檢查 config.json 中 command/args 絕對路徑 |
| JSON 序列化失敗 | 回傳類型不支援 | 轉為 str 或 dict |
| 逾時斷開 | 工具執行太慢 | 改 async + 設 timeout |
| 權限拒絕 | 檔案路徑受限 | 設定允許存取的目錄 allowlist |
FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . EXPOSE 8000 CMD ["python", "server.py"]
部署選項：Railway / Render（個人專案一鍵部署）、AWS Lambda / Google Cloud Run（Serverless）、自建 VPS（Nginx 反向代理）。監控用結構化記錄、Prometheus 指標、Sentry 告警與健康檢查介面。版本管理須宣告 MCP 協定版本，升級工具時保持向後相容。
需求：讓 AI 搜尋本地 Markdown 筆記、語意檢索、建立與更新筆記。技術選型：ChromaDB / Qdrant 向量庫、text-embedding-3-small 嵌入、watchfiles 監聽檔案變化。核心實作：筆記索引工具、語意搜尋工具、筆記寫入工具、檔案資源服務。效果：在 Cursor 中問「我上週記錄了什麼關於 MCP 的筆記？」，Agent 呼叫搜尋工具回傳相關片段。
2026 年主流 AI 客戶端（Cursor、Claude Desktop、VS Code、OpenAI、Gemini）均已支援 MCP；MCP Marketplace 與企業級安全標準快速發展。下一步：深入學習協定規範、發布公開 Server、探索 MCP + Agent 組合、貢獻開源生態。配套資源：Python SDK、TypeScript SDK、MCP Inspector。
tools/list 執行時期拉取。筆電適合 MCP POC，卻在闔蓋休眠、缺少 macOS 原生工具鏈與長期程序守護上削弱 7×24 體驗；純 Linux VPS 能跑 HTTP+SSE，卻難承載 Keychain、Xcode 等 macOS 相依的 MCP 工具。對要把多個 MCP Server 當「常駐基礎設施」、讓 Agent 跨週累積工具呼叫複利的技術團隊，VpsMesh Mac Mini M4 雲端租用把 uptime、遠端 KVM 與可預期月租打包成生產級 OpEx。方案見 Mac Mini M4 租用價格，部署問題見 幫助中心，線上下單見 訂購頁。
Python 官方 SDK mcp 配合 FastMCP 上手最快，適合後端與 AI 工程師。TypeScript SDK @modelcontextprotocol/sdk 適合前端與全端。二者協定層完全相容，邏輯可對照遷移。若團隊主力是 Node 全端，選 TS；若以資料 / ML 為主，選 Python。
Tools 是動作執行者——AI 呼叫後會改變外部狀態或觸發計算（搜尋、寫檔案、發請求）。Resources 是資料提供者——透過 URI 唯讀取得內容，如 config://app-settings 或 user://{id}/profile。簡單記憶：讀資料用 Resource，做動作用 Tool。
HTTP+SSE 模式可部署在 Railway、Cloud Run 或 Linux VPS。若 MCP 工具鏈相依 macOS 原生能力、Keychain 或你希望 Cursor Agent 與多個 Server 7×24 不被闔蓋打斷，Mac Mini M4 月租更省心。建議先租 1 個月驗證 tools/call 曲線，方案見 Mac Mini M4 租用價格，下單見 訂購頁，文檔見 幫助中心。