第 08 章

MCP 服务

用标准协议让 AI 连接整个外部世界

GitHub、数据库、浏览器——MCP 是 AI 与外部系统的通用语言

你已经能让 AI 调用内部工具了。这一章打开外部世界 —— 通过 MCP 接入 GitHub、数据库、浏览器等系统。

看不见外面

AI 能读写你的文件，但碰不到项目之外的世界

看不到 GitHub Issue

你说"按 #123 issue 修个 bug"，AI 不知道 issue 内容，得你复制粘贴给它。

查不了数据库

排查数据问题，AI 不能直接查表，得你手动跑 SQL、贴结果。

操作不了浏览器

测一个网页交互，AI 不能打开浏览器点点看，只能凭代码猜。

MCP 解决的就是"AI 的孤岛问题"：它是一个标准协议，让 AI 通过统一的接口连接各种外部系统——连上之后，AI 就能读 Issue、查数据库、操作浏览器，能力没有边界。

什么是 MCP

定义、白话、和它的野心

MCP（Model Context Protocol，模型上下文协议）是一个开放标准，定义了 AI 应用如何与外部工具、数据源交互。Qoder CLI 通过 MCP 连接各种"MCP 服务"，从而获得操作外部系统的能力。

说白了，MCP 就像 AI 世界的USB 标准——在 MCP 之前，每个外部系统都要 AI 单独写适配；有了 MCP，任何系统只要提供 MCP 服务，AI 就能即插即用地连上。

MCP 的意义：它把"AI + 外部系统"从一对一的硬编码，变成标准化的生态。社区已经为 GitHub、Slack、数据库、浏览器等开发了现成的 MCP 服务，你直接接入即可。

三层架构

理解 MCP 的工作方式

第一层：Qoder CLI（AI）——发出对外部操作的请求。

第二层：MCP 服务——中间翻译层，把 AI 的请求转成对外部系统的具体调用。一个 MCP 服务对应一个外部系统。

第三层：外部系统——GitHub、数据库、浏览器等真正存储数据、执行操作的地方。

关键理解：你不直接让 AI 操作 GitHub，而是让 AI 通过"GitHub MCP 服务"操作 GitHub。这层抽象让协议统一、权限可控、即插即用。

四种传输

MCP 服务和 CLI 之间怎么通信

用 -t 参数选择传输方式，适配不同部署形态：

类型	适用场景	典型例子
`stdio`	MCP 服务作为本地命令运行（默认）	npx 启动的本地服务
`sse`	通过 Server-Sent Events 端点暴露	云端流式服务
`http`	通过 HTTP 端点暴露	远程 REST 服务
`ws`	通过 WebSocket 端点暴露	双向实时通信

新手默认用 stdio 即可。大部分本地 MCP 服务（如 playwright、context7）都是 stdio 类型，qodercli mcp add 不指定 -t 时默认就是 stdio。远程服务才需要 sse/http/ws。

添加服务

一行命令接入一个外部系统

用 qodercli mcp add 添加 stdio 服务，-- 后面是要启动的服务进程命令：

qodercli mcp add playwright -- npx -y @playwright/mcp@latest

这条命令做三件事：① 注册一个名为 playwright 的 MCP 服务；② 用 npx 启动 @playwright/mcp 进程；③ 该进程作为 stdio 服务与 CLI 通信。

管理命令：

qodercli mcp list                  # 查看已配置的服务
qodercli mcp remove playwright      # 移除某个服务
/mcp reload                         # CLI 运行中重新加载（会话内）

新会话自动发现：添加服务后，新启动的 CLI 会自动加载。如果 CLI 正在运行，需要执行 /mcp reload 才能在当前会话使用新服务。

三级作用域

MCP 服务配置存哪里，决定了谁能用

用 -s 选择配置保存位置（默认 local）：

作用域	存储文件	适用场景
`user`	`~/.qoder/settings.json`	当前账号的所有项目都要用
`local`	`项目/.qoder/settings.local.json`	只在本机当前项目用（默认，不提交）
`project`	`项目/.mcp.json`	团队共享，随 Git 提交

团队协作实践：通用服务（如 GitHub、数据库）用 project 作用域存进 .mcp.json 提交共享；个人实验的服务用 local，不污染团队配置。

权限控制

MCP 工具同样经过权限系统，且可细粒度配置

MCP 服务提供的工具，命名格式为 mcp__<server>__<tool>。它们和内置工具一样，要经过权限检查。

在默认模式下，调用 MCP 工具通常会请求确认。你可以在 settings 里预先配置规则免确认：

{
  "permissions": {
    "allow": [
      "mcp__context7__*"          // 允许 context7 的所有工具
    ],
    "ask": [
      "mcp__github__create_issue" // 创建 issue 仍需确认
    ]
  }
}

支持的匹配模式

mcp__github__create_issue——单个工具
mcp__github__*——某 server 下所有工具
mcp__github——同上的简写
mcp__*——所有 MCP 工具

按需启用 server

某次运行只想用指定 MCP server：

qodercli --allowed-mcp-server-names \
  context7,github

权限系统的完整讲解见第 11 章。这里只需知道：MCP 工具不是"接入就能随便用"，而是受权限系统管控，安全可控。

排错指南

MCP 相关的高频问题

MCP 工具不可用

排查步骤：① qodercli mcp list 确认服务已配置；② CLI 运行中执行 /mcp reload；③ 确认 -- 后的命令能在终端独立运行；④ npx 服务确认 Node.js 和网络可用。

工具调用被阻止

原因：权限规则没放行。修复：检查 settings 的 allow 规则；或调用时确认授权；或在 alwaysAllow 里为该 server 设置自动允许。

npx 服务启动慢/失败

原因：首次下载包慢，或网络受限。修复：配置 npm 镜像；或预先 npm install -g 该包；企业网络配代理。

会话内没发现新服务

原因：CLI 运行中添加的服务不会自动加载。修复：执行 /mcp reload，或新开会话。

排错指南

MCP 服务接入中的高频问题

MCP 服务连不上

原因：网络问题、服务地址错误、或启动命令有误。修复：用 qodercli mcp list 检查服务状态；手动运行启动命令验证；检查防火墙和代理设置。

MCP 工具调用被权限拒绝

原因：权限规则未配置或 deny 规则优先。修复：在 settings.json 中为 mcp__server__tool 添加 allow 规则；检查 deny 规则是否误拦截。

工具列表为空

原因：服务注册成功但未正确暴露工具。修复：重启会话（/mcp reload）；检查 MCP 服务日志；确认服务实现了 list_tools。

响应超时

原因：MCP 服务处理慢或网络延迟高。修复：增加超时配置；检查服务端性能；考虑本地部署替代远程服务。

动手练习

接入一个 MCP 服务，感受 AI 能力的扩展

练习 1：接入 context7

运行 qodercli mcp add context7 -- npx -y @upstash/context7-mcp@latest
用 qodercli mcp list 确认已添加
新开会话或 /mcp reload

练习 2：使用 MCP 工具

问 AI"用 context7 查 React 18 useEffect 的最新文档"
观察 AI 如何调用 MCP 工具获取实时信息
对比不接 MCP 时 AI 凭记忆回答的差异

练习 3：配置权限

在 settings 里给 mcp__context7__* 加 allow 规则
下次调用该服务工具不再弹确认

本章回顾

带走的三个核心认知

MCP 是 USB 标准

AI 与外部系统的统一协议，即插即用，能力无限扩展。

三层架构

CLI → MCP 服务 → 外部系统，中间层做翻译和隔离。

权限可控

MCP 工具受权限系统管控，可按 server、按工具细粒度配置。

核心结论：MCP 让 AI 从"只能看你本地文件"变成"能操作整个数字世界"。接入多少服务，AI 就有多大的能力边界——而这个边界由你决定。

下一章，学习钩子（Hooks）——在工具调用前后插入自动检查，让自动化更进一步。

MCP 服务

看不见外面

AI 能读写你的文件，但碰不到项目之外的世界

看不到 GitHub Issue

查不了数据库

操作不了浏览器

什么是 MCP

定义、白话、和它的野心

三层架构

理解 MCP 的工作方式

图：MCP 三层调用架构

四种传输

MCP 服务和 CLI 之间怎么通信

添加服务

一行命令接入一个外部系统

三级作用域

MCP 服务配置存哪里，决定了谁能用

推荐服务

几个高价值、开箱即用的 MCP 服务

context7 — 实时文档

deepwiki — 仓库百科

chrome-devtools — 浏览器

playwright — 浏览器自动化

权限控制

MCP 工具同样经过权限系统，且可细粒度配置

支持的匹配模式

按需启用 server

排错指南

MCP 相关的高频问题

MCP 工具不可用

工具调用被阻止

npx 服务启动慢/失败

会话内没发现新服务

排错指南

MCP 服务接入中的高频问题

MCP 服务连不上

MCP 工具调用被权限拒绝

工具列表为空

响应超时

动手练习

接入一个 MCP 服务，感受 AI 能力的扩展

练习 1：接入 context7

练习 2：使用 MCP 工具

练习 3：配置权限

本章回顾

带走的三个核心认知

MCP 是 USB 标准

三层架构

权限可控

延伸阅读

继续本课程

官方资源