開發工具2026年6月14日

Claude + MCP 實戰教學：我把踩過的坑全攤出來給你看

AI 觀察家

專欄作者 · 2313 字

重點摘要

MCP 不是插件，是協議層：搞懂這個，你才不會一直在錯的地方找問題。
Claude + MCP 的組合，坑主要集中在三個地方：伺服器連線、工具描述寫法、context 用量控制。
跑通之後，Coding 效率的提升是真實的：不是行銷話術，但前提是你得先把架構設對。

為什麼 MCP 和 Claude 的組合這麼難上手？

直接說結論：因為大部分教學都在講「MCP 是什麼」，卻沒人告訴你「連上去之後為什麼不動」。

MCP（Model Context Protocol）是 Anthropic 在 2024 年底推出的開放協議，設計目標是讓 AI 模型能夠跟外部工具、資料來源建立標準化的溝通介面。換句話說，它不是 Claude 的某個功能按鈕，而是一套讓 Claude 「看得懂」外部工具的語言規範。

問題在於，這套協議的生態系還很新。官方文件寫得頗為學術，社群裡的範例程式碼版本又常常對不上，許多開發者第一次跑，根本不確定自己是設定錯了、還是工具本身有 bug。

怎麼把 MCP 伺服器跑起來？

先把環境確認清楚，這步跳掉後面一定卡。

基本前置條件：

Node.js 18 以上（MCP SDK 有版本要求）
安裝 @anthropic-ai/sdk 與 @modelcontextprotocol/sdk
Claude API Key（用 claude-3-5-sonnet 或更新的模型）

最小可跑的 MCP Server 結構（以 TypeScript 為例）：

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
  { name: 'my-coding-tools', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

// 在這裡註冊你的工具
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'read_file',
    description: '讀取指定路徑的檔案內容',
    inputSchema: {
      type: 'object',
      properties: { path: { type: 'string' } },
      required: ['path']
    }
  }]
}));

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

這是最簡版本。很多教學跳過了 StdioServerTransport 這個細節——MCP 預設用標準輸入輸出溝通，不是 HTTP，這個搞錯方向會浪費你很多時間。

為什麼工具描述寫不好、Claude 就不會用？

這是我觀察到開發者最常忽略的地方，也是真正影響 Coding 輔助品質的核心。

Claude 決定要不要呼叫某個工具，靠的是 description 欄位。這不是給人看的備注，是給模型做決策的 prompt。

差的寫法 vs 好的寫法：

	差的	好的
read_file	「讀檔案」	「讀取本地檔案系統中指定路徑的文字內容，適合在需要查看程式碼、設定檔或文字資料時使用」
run_command	「執行指令」	「在專案根目錄執行 shell 指令並回傳 stdout/stderr，適合跑測試、build 或 lint 等開發指令」
search_code	「搜尋程式碼」	「在指定目錄內以關鍵字搜尋程式碼，回傳符合的行號與上下文，適合定位特定函式或變數的使用位置」