MCP 实战指南

上一篇我们让 AI 连上了信息源和推送渠道。但那些连接是"写死在某个工作流里"的。如果换一个 AI 客户端、换一个项目，是不是要重连一遍？MCP（Model Context Protocol，模型上下文协议） 就是来解决这个问题的——它是 2026 年 Agent 连接外部工具的"通用插头"。结论先行：不懂 MCP，你每接一个工具都要和每个客户端单独适配；懂了 MCP，一次写好、处处可用。

本文承接《Agent 与 MCP》的原理，带你从架构走到动手：先在客户端配好现成 Server，再自己写一个。

本页直达：配置现成 Server · 权限边界 · 自己写一个 Python Server · 调试与验收。完整业务项目见把查询能力做成 MCP Server。

1. MCP 是什么，为什么 2026 年必须懂

《Agent 与 MCP》讲过：Agent = 模型 + 工具 + 循环。工具从哪来？2024 年以前，每个 AI 应用各写各的集成，重复劳动且不互通。Anthropic 提出 MCP，把"AI 怎么调用外部工具"标准化。

一个类比反复被用：MCP 之于 AI 工具，就像 USB 之于外设。以前每个设备一个专用口，现在统一插口——任何支持 MCP 的客户端（Claude Code、Cursor、Dify 等）都能接上任何 MCP Server 提供的工具。

2026 年的事实是：MCP 已成 Agent 工具调用的事实标准。Claude Code、Cursor、Dify 等主流客户端均已支持，社区 Server 覆盖文件系统、代码仓库、数据库、浏览器、通讯工具；2025 年 12 月起，MCP 由 Linux 基金会旗下 Agentic AI Foundation 中立治理，Anthropic 已将协议捐入（截至 2026-09 核对）。你写的自动化越多，越会发现"用 MCP 接工具"比"为每个客户端单独写适配"省一个数量级的力气。

2. Host / Client / Server 架构

MCP 是客户端-服务器架构，三个角色职责清晰：

角色	是什么	例子	负责
Host（主机）	运行 AI、承载对话的应用	Claude Code、Cursor、Dify	发起任务、调模型、决定何时用工具
Client（客户端）	Host 内部的连接器，一对一连一个 Server	每个 MCP Server 对应一个 Client	把 Host 的请求翻译成 MCP 协议发给 Server
Server（服务器）	提供具体能力的进程	文件系统 Server、GitHub Server	真去读文件/查 Issue/跑查询，返回结果

text

[用户] → [Host: Claude Code]
              │ 内部
              ├─ [MCP Client A] ──→ [MCP Server: 文件系统]
              ├─ [MCP Client B] ──→ [MCP Server: GitHub]
              └─ [MCP Client C] ──→ [MCP Server: 数据库]

关键点：一个 Host 可以有多个 Client，每个 Client 只连一个 Server（一对一）。Server 是独立进程，Host 通过标准输入/输出（stdio）或网络（Streamable HTTP）和它通信——早期的 HTTP+SSE 传输已废弃，新实现不要再用。你加一个新能力，就是"再加一个 Server"，不动 Host 代码。

3. 在 Claude Code 中配置 MCP Server

Claude Code 原生支持 MCP。配置有两种：写进项目级 .mcp.json，或用命令添加。

3.1 方式一：命令行添加（最快）

bash

# 添加一个通过 npx 启动的 Server（filesystem 是仍在维护的官方参考实现）
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /abs/path/to/allowed/dir

# 查看已配置的 Server
claude mcp list

# 删除
claude mcp remove filesystem

生态现状（2026-09 核对）：Server 的包名与维护方会变。官方参考实现中 GitHub、GitLab、PostgreSQL、Slack 等已归档移交（见 modelcontextprotocol/servers-archived），改由产品方维护——例如 GitHub 官方 Server 现在是 github/github-mcp-server，旧 npm 包 @modelcontextprotocol/server-github 已弃用。配置前先查 modelcontextprotocol/servers 仓库与官方 MCP Registry 的现状。

3.2 方式二：写 `.mcp.json`（可提交、可复用）

在项目根目录建 .mcp.json：

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/abs/path/to/allowed/dir"]
    }
  }
}

安全红线：不要把真实 Token 写进文件。用环境变量注入（${GITHUB_TOKEN}）或密钥管理服务。细节见《AI 使用安全清单》。/abs/path/to/allowed/dir 限定文件系统 Server 只能访问这个目录——这是权限最小化的体现。

3.3 验证

配置后重启 Claude Code，问它"列出 /allowed/dir 下的文件"或"查一下我的 GitHub Issue"，看它是否调用了对应工具。能调通，说明 Client↔Server 通了。

4. 在 Cursor 中配置 MCP Server

Cursor 的配置在 Settings → MCP → Add Server，或直接编辑 ~/.cursor/mcp.json（全局）与项目级 .cursor/mcp.json。

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/abs/path/to/allowed/dir"]
    }
  }
}

保存后在 MCP 面板看到绿点即表示连上。Cursor 与 Claude Code 的配置结构一致——这正是 MCP 的"一次写、处处用"价值。

5. 五个最实用的 MCP Server

下面逐个讲清楚"它干嘛用、怎么配、何时用"。

5.1 文件系统 Server（filesystem）

干嘛用：让 AI 读/写/搜指定目录下的文件，是本地自动化最基础的"手脚"。 怎么配：见第 3.2 节，关键是把可访问路径限制在必要目录。 何时用：整理文档、批量改名、按规则生成报告。配合《第一个自动化工作流实战》的本地文件输出很顺。

5.2 GitHub Server（github）

干嘛用：提 PR、查 Issue、读仓库、建分支——把"代码协作"交给 Agent。 怎么配：官方 Server 已迁移到 github/github-mcp-server（提供远程端点与本地运行两种方式），旧 npm 包已弃用。用细粒度令牌（只给需要的 repo 权限），注入方式见其仓库 README。 何时用：让 Agent 自主修复 Issue、生成变更摘要、监控仓库动态。

5.3 Playwright 浏览器 Server（playwright）

干嘛用：让 AI 真正"打开网页"——点击、填表、截图、抽取动态内容。 怎么配：npx @playwright/mcp@latest，首次会自动装浏览器。 何时用：抓取 JS 渲染的页面、做网页端自动化测试、填表单。这是很多"信息源监控"的兜底方案（当 RSS 没有时）。

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--headless"]
    }
  }
}

5.4 数据库 Server（如 sqlite / postgres）

干嘛用：让 AI 直接跑 SQL 查询你的业务库，把"问数据"变成自然语言。 怎么配：官方参考实现里的 sqlite/postgres Server 已归档（见 3.1 节的生态现状提示），改用社区维护的数据库 Server 或产品自带的 MCP 支持；连接串用只读账号。 何时用：每日数据汇总、临时分析、生成报表——把《第一个自动化工作流实战》的"抓取"换成"查库"。

5.5 搜索 Server（如 brave-search / exa）

干嘛用：让 Agent 联网检索，弥补模型训练数据截止的短板。 怎么配：注入搜索 API Key（如 Brave Search API）。 何时用：写需要最新事实的内容、做竞品调研、验证说法。注意搜索结果要交叉核对，别盲信。

6. 安全边界：权限最小化

MCP 把"手脚"交给 AI，也把"出事面"扩大了。三条底线：

目录最小：文件系统 Server 只暴露必要目录，绝不给整个 home。
令牌最小：GitHub/数据库令牌用细粒度权限、只读优先，过期时间设短。
人工确认：危险动作（删文件、push 到 main、发消息）让 Host 弹确认，不全自动。

风险	错误做法	正确做法
越权读文件	暴露 `/` 或 home	只暴露 `/abs/path/to/allowed/dir`
令牌泄露	明文写进 `.mcp.json` 并提交	环境变量注入 + `.gitignore`
误删	全自动执行写操作	关键写操作人工确认
滥用搜索	无限制联网	限定域名/配额

完整清单见《AI 使用安全清单》。一句话：工具越能干活，越要拴好缰绳。

7. 自己写一个简单 MCP Server（Python）

下面用只读服务状态查询练习最小闭环。若要接入真实业务数据和多个客户端，再按《把一个查询能力做成 MCP Server》设计数据层、权限和部署。

示例使用官方 Python SDK v2 的 MCPServer。工具只读固定样本，不访问真实服务或凭证。

先安装：

bash

pip install "mcp[cli]"

下面是一个"天气/行情查询"风格的极简 Server，暴露一个工具 get_status：

python

# server.py
from mcp.server import MCPServer

mcp = MCPServer("demo-server")

@mcp.tool()
def get_status(service: str) -> str:
    """查询某个内部服务的运行状态，返回 ok / down。"""
    # 真实场景应在服务层完成认证和数据查询
    fake = {"api": "ok", "db": "ok", "cache": "down"}
    return fake.get(service, "unknown")

@mcp.resource("config://version")
def version() -> str:
    """暴露一个只读资源：当前服务版本。"""
    return "v1.0.0"

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

把它接进客户端：

json

{
  "mcpServers": {
    "demo": {
      "command": "python",
      "args": ["/abs/path/to/server.py"]
    }
  }
}

重启客户端后，问“查一下 cache 服务状态”，检查客户端是否调用 get_status，并返回 down。再试一个不存在的服务名，应返回 unknown。@mcp.tool() 暴露可调用方法，@mcp.resource() 暴露只读数据。参数类型标注会生成工具的输入 Schema。官方入门文档给出了完整验证步骤。

8. 调试自己的 Server

现象	原因	排查
客户端找不到工具	Server 没启动/路径错	命令行先 `python server.py` 看是否报错
工具列表为空	没用 `@mcp.tool()` 装饰	确认函数被装饰且可被导入
调用报参数错	类型标注缺失	给参数加类型注解（如 `service: str`）
中文乱码	终端编码	声明 UTF-8 运行环境

先用官方 CLI 启动 Inspector，分别检查工具列表、cache 的返回值，以及未知服务名的返回值：

bash

mcp dev server.py

9. 把 MCP 接进工作流

MCP 不只服务于聊天客户端。在 n8n/Dify 里，MCP 让你复用同一组工具，不必为每个流程重写集成：

n8n 有 MCP 触发器/节点，可调用任意 MCP Server。
Dify 已支持 MCP，通过插件与工具节点接入外部 Server（支持范围与接入方式以 Dify 官方文档为准）。
你自己写的内部 Server，也能被《第一个自动化工作流实战》的情报流调用（例如"查内部数据库生成日报"）。

这也呼应《四大平台横评与选型》第 13 节的"组合拳"：用 MCP 当胶水，把平台与你的系统粘起来。

10. 动手检查清单

[ ] 在 Claude Code 或 Cursor 配通至少一个现成 Server（如 filesystem）。
[ ] 确认 Token 走环境变量，未明文入库。
[ ] 文件系统 Server 只暴露必要目录（权限最小化）。
[ ] 跑通"用自然语言调用工具"的一次对话。
[ ] （进阶）照第 7 节写一个自己的 Server 并接进客户端。
[ ] 危险动作保持人工确认，不全自动。

11. 术语对照

术语	一句话解释
MCP	模型上下文协议，AI 连接外部工具的通用标准
Host	运行 AI 的应用，如 Claude Code、Cursor
Client	Host 内部一对一连接某个 Server 的部件
Server	提供具体工具能力的独立进程
MCPServer	Python SDK v2 中用于声明工具、资源并运行 Server 的类
资源 Resource	Server 暴露的只读数据，区别于可执行的工具

12. 下一步

想从原理理解工具调用循环 → 《Agent 与 MCP》。
想按真实任务把自己公司的查询能力做成 Server → 《实战：把一个查询能力做成 MCP Server》。
想把工具设计成生产级 → 《工具设计与 MCP》。
想搭工作流用上 MCP → 《第一个自动化工作流实战》《四大平台横评与选型》。
想看产业里 MCP 的位置 → 《2026 技术雷达与大事记》。

MCP 是"让 AI 真正动手"的底座。配通第一个 Server，你就拥有了可无限扩展的"工具箱"——而工具箱越满，你的自动化越接近一人公司的形态（见《AI 员工编队与工具栈》）。

MCP 实战指南 ​

1. MCP 是什么，为什么 2026 年必须懂 ​

2. Host / Client / Server 架构 ​

3. 在 Claude Code 中配置 MCP Server ​

3.1 方式一：命令行添加（最快） ​

3.2 方式二：写 .mcp.json（可提交、可复用） ​

3.3 验证 ​

4. 在 Cursor 中配置 MCP Server ​

5. 五个最实用的 MCP Server ​

5.1 文件系统 Server（filesystem） ​

5.2 GitHub Server（github） ​

5.3 Playwright 浏览器 Server（playwright） ​

5.4 数据库 Server（如 sqlite / postgres） ​

5.5 搜索 Server（如 brave-search / exa） ​

6. 安全边界：权限最小化 ​

7. 自己写一个简单 MCP Server（Python） ​

8. 调试自己的 Server ​

9. 把 MCP 接进工作流 ​

10. 动手检查清单 ​

11. 术语对照 ​

12. 下一步 ​

MCP 实战指南

1. MCP 是什么，为什么 2026 年必须懂

2. Host / Client / Server 架构

3. 在 Claude Code 中配置 MCP Server

3.1 方式一：命令行添加（最快）

3.2 方式二：写 `.mcp.json`（可提交、可复用）

3.3 验证

4. 在 Cursor 中配置 MCP Server

5. 五个最实用的 MCP Server

5.1 文件系统 Server（filesystem）

5.2 GitHub Server（github）

5.3 Playwright 浏览器 Server（playwright）

5.4 数据库 Server（如 sqlite / postgres）

5.5 搜索 Server（如 brave-search / exa）

6. 安全边界：权限最小化

7. 自己写一个简单 MCP Server（Python）

8. 调试自己的 Server

9. 把 MCP 接进工作流

10. 动手检查清单

11. 术语对照

12. 下一步