MCP 實戰教程：2026 年用 Model Context Protocol 構建可靠的 AI Agent 工作流

你有沒有遇過這種情況：花了一整天配置 AI 助手，讓它能讀取本地文件、查詢資料庫、調用 API，結果每次換個工具就要重新寫一遍集成代碼？或者團隊裡每個人都在用不同的方式連接 LLM 和工具，維護起來像一場災難？

這正是 Model Context Protocol (MCP) 要解決的問題。2025 年 12 月，Linux Foundation 成立了 Agentic AI Foundation (AAIF)，Anthropic、OpenAI、Google、Microsoft 等科技巨頭都是創始成員。他們推動的核心標準之一就是 MCP，一個被稱為「AI 應用的 USB-C 接口」的開源協議。

這篇教程會帶你從零開始理解 MCP，並用實際代碼構建一個可運行的 AI Agent 工作流。

為什麼需要 MCP？

在 MCP 出現之前，每個 AI 應用都要自己實現工具調用邏輯。假設你想讓 Claude 讀取 Google Drive 文件：

你需要處理 OAuth 認證
實現 Google Drive API 調用
設計工具描述格式讓 LLM 理解
處理錯誤和重試邏輯
確保數據安全傳輸

現在換成 Notion？重來一遍。換成 GitHub？再來一遍。每個工具都是一套獨立的集成代碼。

MCP 的核心思想很簡單：把工具暴露和工具調用標準化。就像 USB-C 讓所有設備都能用同一種接口充電和傳輸數據，MCP 讓所有 AI 應用都能用同一種方式訪問工具。

根據 Anthropic 的數據，使用 MCP 可以將集成延遲降低 40%，而且一次編寫的 MCP Server 可以被任何支持 MCP 的客戶端使用。

MCP 核心架構

MCP 採用三層架構：

┌─────────────────┐
│   MCP Host      │  ← AI 應用（Claude Desktop、IDE、自定義應用）
│  (LLM 應用層)   │
└────────┬────────┘
         │
┌────────▼────────┐
│   MCP Client    │  ← 協議實現層（處理通信、認證、錯誤）
│  (協議實現層)   │
└────────┬────────┘
         │
┌────────▼────────┐
│   MCP Server    │  ← 工具暴露層（Google Drive、Slack、資料庫）
│  (工具暴露層)   │
└─────────────────┘

三個核心概念

MCP Host：運行 LLM 的應用程序（比如 Claude Desktop、Cursor、你自己的 AI 應用）
MCP Client：實現 MCP 協議的客戶端庫，負責與 Server 通信
MCP Server：暴露具體工具能力的服務（可以是本地進程或遠程服務）

關鍵點：Host 和 Server 之間通過標準化的 JSON-RPC 協議通信。這意味著你寫的 MCP Server 可以被任何支持 MCP 的 Host 使用。

實戰：構建你的第一個 MCP Server

我們來構建一個實用的 MCP Server，讓 AI 助手能夠讀取和搜索本地 Markdown 文件。這在管理個人知識庫或文檔時非常有用。

步驟 1：環境準備

# 創建項目目錄
mkdir my-mcp-server
cd my-mcp-server

# 安裝 FastMCP（Anthropic 官方推薦的 Python 框架）
pip install fastmcp

# 創建主文件
touch server.py

步驟 2：實現 MCP Server

from fastmcp import FastMCP
from pathlib import Path
from typing import List

# 初始化 MCP Server
mcp = FastMCP("markdown-knowledge-base")

# 工具 1：列出所有 Markdown 文件
@mcp.tool()
def list_markdown_files(directory: str = ".") -> List[str]:
    """
    列出指定目錄下的所有 Markdown 文件

    Args:
        directory: 要搜索的目錄路徑（默認為當前目錄）
    Returns:
        Markdown 文件路徑列表
    """
    path = Path(directory)
    if not path.exists():
        return [f"錯誤：目錄 {directory} 不存在"]
    md_files = list(path.rglob("*.md"))
    return [str(f.relative_to(path)) for f in md_files]

# 工具 2：讀取 Markdown 文件內容
@mcp.tool()
def read_markdown_file(file_path: str) -> str:
    """讀取指定 Markdown 文件的內容"""
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            return f.read()
    except FileNotFoundError:
        return f"錯誤：文件 {file_path} 不存在"
    except Exception as e:
        return f"錯誤：無法讀取文件 - {str(e)}"

# 工具 3：搜索 Markdown 文件內容
@mcp.tool()
def search_markdown_content(
    keyword: str, directory: str = "."
) -> List[dict]:
    """在 Markdown 文件中搜索關鍵詞"""
    path = Path(directory)
    results = []
    for md_file in path.rglob("*.md"):
        try:
            with open(md_file, 'r', encoding='utf-8') as f:
                lines = f.readlines()
            matches = [
                {"line_number": i+1, "content": line.strip()}
                for i, line in enumerate(lines)
                if keyword.lower() in line.lower()
            ]
            if matches:
                results.append({
                    "file": str(md_file.relative_to(path)),
                    "matches": matches
                })
        except Exception:
            continue
    return results

# 啟動 Server
if __name__ == "__main__":
    mcp.run()

步驟 3：配置 MCP Client

如果你使用 Claude Desktop，需要在配置文件中添加這個 Server：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "markdown-kb": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {}
    }
  }
}

重啟 Claude Desktop，你就能在對話中使用這些工具了：

你：幫我找出所有提到「MCP」的筆記
Claude：[調用 search_markdown_content 工具]
      找到 3 個文件包含「MCP」...

進階技巧

1. 添加資源（Resources）

除了工具（Tools），MCP 還支持暴露資源（Resources）：

@mcp.resource("markdown://{file_path}")
def get_markdown_resource(file_path: str) -> str:
    """將 Markdown 文件暴露為 MCP 資源"""
    with open(file_path, 'r', encoding='utf-8') as f:
        return f.read()

2. 實現提示詞模板（Prompts）

你可以預定義常用的提示詞模板：

@mcp.prompt()
def summarize_markdown(file_path: str) -> str:
    """生成 Markdown 文件摘要的提示詞"""
    content = read_markdown_file(file_path)
    return f"""請為以下 Markdown 文件生成摘要：

{content}

摘要要求：
- 不超過 3 句話
- 提取核心觀點
- 使用繁體中文"""

3. 錯誤處理和日誌

生產環境中要做好錯誤處理：

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@mcp.tool()
def safe_read_file(file_path: str) -> str:
    try:
        logger.info(f"讀取文件: {file_path}")
        with open(file_path, 'r', encoding='utf-8') as f:
            return f.read()
    except FileNotFoundError:
        logger.error(f"文件不存在: {file_path}")
        return "錯誤：文件不存在"
    except PermissionError:
        logger.error(f"權限不足: {file_path}")
        return "錯誤：沒有讀取權限"

多代理協作：A2A 協議

MCP 解決了工具集成問題，但如果你需要多個 AI Agent 協作呢？這就是 A2A (Agent-to-Agent) 協議的用武之地。

A2A 是 AAIF 推動的另一個標準，讓不同的 Agent 可以互相通信和委派任務。典型場景：

研究 Agent 收集信息 → 分析 Agent 處理數據 → 寫作 Agent 生成報告
客服 Agent 識別問題 → 技術 Agent 提供解決方案

A2A 和 MCP 的關係：MCP 是 Agent 與工具的接口，A2A 是 Agent 與 Agent 的接口。

常見問題

Q: MCP Server 必須用 Python 寫嗎？ A: 不是。官方提供了 Python (FastMCP) 和 TypeScript SDK，社群也有 Rust、Go 等實現。

Q: MCP 和 LangChain Tools 有什麼區別？ A: LangChain Tools 是框架特定的，只能在 LangChain 生態中使用。MCP 是跨框架的標準，任何支持 MCP 的應用都能使用你的 Server。

Q: 如何保證 MCP Server 的安全性？ A: 三個關鍵點：使用環境變量管理敏感信息、實現權限檢查（限制可訪問的文件/目錄）、對外部輸入做驗證和清理。

Q: MCP 支持遠程 Server 嗎？ A: 支持。你可以通過 HTTP/WebSocket 運行遠程 MCP Server，適合團隊共享工具或雲端部署。

學習資源

官方文檔：modelcontextprotocol.io
FastMCP GitHub：github.com/jlowin/fastmcp
MCP Servers 集合：github.com/modelcontextprotocol/servers
AAIF 官網：agentic.foundation

下一步

現在你已經掌握了 MCP 的核心概念和實戰技巧。建議你：

選擇一個實際場景（比如自動化工作流、數據分析、內容管理）
用 FastMCP 實現一個 Server
在 Claude Desktop 或自己的應用中測試
考慮開源分享給社群

MCP 的價值在於生態。當越來越多開發者貢獻 Server，AI Agent 的能力邊界就會不斷擴展。你寫的每一個 MCP Server，都可能成為別人構建下一個殺手級應用的基石。

開始動手吧，2026 年的 AI 應用開發，標準化是第一步。