MCP 协议实战：从 mcp.json 配置到多工具串联，让 AI Agent 连上外部世界

适合用过 AI 编程助手或 AI Agent、想让它真正操作外部工具（数据库、文档、API）的开发者。
本文从配置到调试到多工具串联，走一遍完整流程，附可运行的示例。

MCP 是什么，为什么你需要它

你有没有遇到过这种情况：让 AI 帮你查个数据库、发条消息、读个文档，它只能给你一段代码让你自己跑？

原因很简单——AI 模型默认是"关在房间里的"，它看不到外面的世界，也碰不到你的工具。

MCP（Model Context Protocol）就是解决这个问题的。它是 Anthropic 推出的一个开放协议，标准化了 AI 模型和外部工具之间的通信方式。你可以把它理解成 AI 的 USB 接口——有了它，AI Agent 就能像插 U 盘一样，连上数据库、消息服务、文档系统、API 等各种外部工具。

核心概念只有 3 个：

概念	是什么	类比
MCP Server	提供工具能力的服务端	U 盘里的文件
MCP Client	调用工具的 AI 应用	电脑的 USB 口
mcp.json	告诉 Client 去哪找 Server 的配置文件	告诉电脑 U 盘插在哪个口

整个协议的交互流程：

用户提问 → AI 模型判断需要调用工具 → 通过 MCP 协议调用 Server → Server 执行并返回结果 → AI 模型整合结果回答用户

mcp.json 配置详解

MCP 的核心配置文件就是 mcp.json，格式很简单：

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

每个 Server 就是一个 key-value 对，key 是你给它起的名字，value 包含以下字段：

字段	必填	说明
command	是	启动命令（npx、node、python 等）
args	否	命令参数，数组形式
env	否	环境变量，通常用来传 API Key
headers	否	HTTP 请求头，用于需要认证的远程服务
url	否	远程 MCP Server 的地址（替代 command+args）

本地 Server vs 远程 Server

MCP Server 有两种部署方式：

类型	配置方式	适用场景	示例
本地 Server	command + args	工具运行在本机	Playwright 浏览器控制、本地文件操作
远程 Server	url + headers	工具在云端	云文档、消息服务、SaaS API

本地 Server 的配置：

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

远程 Server 的配置：

{
  "mcpServers": {
    "cloud-docs": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

实战 1：连上文档系统（以腾讯文档为例）

这是我日常用得最多的一个 MCP 连接——让 AI Agent 直接读写在线文档。

配置步骤

第一步：获取 API 凭证。去腾讯文档开放平台申请，拿到 Access Token。

第二步：写配置。

{
  "mcpServers": {
    "tencent-docs": {
      "url": "https://mcp.tencent-docs.com/sse",
      "headers": {
        "Authorization": "Bearer tds_xxxxxxxxxxxx"
      }
    }
  }
}

第三步：验证连接。在 AI 助手的连接器管理页面，找到新添加的 Server，点击"信任"激活。然后试着让 AI 读一篇文档：

用户：帮我读一下这篇文档的内容
AI：（调用 mcp__tencent-docs__read_doc 工具）
AI：这篇文档的内容是...

实际效果

连上之后，AI Agent 能做的事情：

能力	说明
读文档	获取文档内容、表格数据
写文档	创建新文档、追加内容
列表	列出文件夹下的所有文档
搜索	按关键词搜索文档

之前让我手动复制粘贴文档内容给 AI，现在一句话搞定。

实战 2：连上知识库（以 IMA 为例）

知识库是另一个高频场景——我有一个包含 200+ 篇资料的知识库，之前每次都要手动搜索再粘贴给 AI。

配置

{
  "mcpServers": {
    "ima-mcp": {
      "url": "https://mcp.ima.qq.com/sse",
      "headers": {
        "Authorization": "Bearer ima_xxxxxxxxxxxx"
      }
    }
  }
}

实际使用

连上之后，AI Agent 可以直接搜索和读取知识库内容：

能力	说明	我的使用场景
搜索笔记	按关键词搜索知识库	写文章时查历史素材
获取笔记内容	读取指定笔记的完整内容	复用以前写过的段落
创建笔记	新建一条笔记	记录灵感和选题
列出笔记本	浏览知识库目录结构	了解素材分布

最大的变化：写文章时 AI 能自动检索相关素材，不用我手动喂了。

实战 3：连上团队知识库（以乐享为例）

如果你有团队协作需求，乐享知识库的 MCP 也是个好例子。它有 4 种实体类型：team（团队）、kb（知识库）、folder（文件夹）、doc（文档）。

配置

{
  "mcpServers": {
    "lexiang": {
      "url": "https://mcp.lexiang.qq.com/sse",
      "headers": {
        "Authorization": "Bearer lx_xxxxxxxxxxxx"
      }
    }
  }
}

关键点：用 ID 而不是名字

乐享的 MCP 工具支持通过 ID 直接定位实体，这比按名字搜索准确得多：

# 好的做法：用 ID
mcp__lexiang__get_doc_content(docId="abc123")

# 不好的做法：按名字搜（可能搜到多个结果）
mcp__lexiang__search_docs(query="周报模板")

多工具串联：让 AI Agent 同时操作多个系统

MCP 真正的威力在于多工具串联——一个任务同时调用多个 MCP Server。

场景：从知识库取素材 → 写文章 → 发到文档

这是我的日常工作流：

用户：帮我写一篇关于 XX 的文章，参考知识库里的素材，写完发到腾讯文档

AI 的执行过程：
1. 调用 ima-mcp 搜索知识库 → 找到相关素材
2. 基于素材 + 用户要求 → 生成文章
3. 调用 tencent-docs 创建新文档 → 写入文章内容
4. 返回文档链接给用户

一个任务串联了 3 个 MCP Server，用户全程零手动操作。

场景：自动整理会议纪要

用户：把上周的会议录音整理成纪要，发到乐享

AI 的执行过程：
1. 读取本地录音文件 → 转写文字（本地 Server）
2. 整理成结构化纪要 → AI 生成
3. 调用 lexiang 创建文档 → 写入纪要

mcp.json 多 Server 完整配置示例

{
  "mcpServers": {
    "tencent-docs": {
      "url": "https://mcp.tencent-docs.com/sse",
      "headers": {
        "Authorization": "Bearer tds_xxxxxxxxxxxx"
      }
    },
    "ima-mcp": {
      "url": "https://mcp.ima.qq.com/sse",
      "headers": {
        "Authorization": "Bearer ima_xxxxxxxxxxxx"
      }
    },
    "lexiang": {
      "url": "https://mcp.lexiang.qq.com/sse",
      "headers": {
        "Authorization": "Bearer lx_xxxxxxxxxxxx"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

MCP Server 类型对比

用了几个月 MCP 之后，我总结了不同类型的 MCP Server 的特点：

类型	代表	优点	缺点
官方云服务	腾讯文档、乐享	稳定、有文档、有技术支持	需要申请凭证
开源社区	Playwright、文件系统	免费、可自定义	需要本地安装依赖
自建 Server	自己写的 API 包装	完全可控	开发成本高
聚合平台	Smithery、mcp.run	一键安装、种类多	质量参差不齐

选型建议

你的需求	推荐方案
操作常见 SaaS（文档、消息）	官方云服务
操作本地工具（浏览器、文件）	开源社区
包装自己的 API	自建 Server
快速试用各种工具	聚合平台

踩坑记录

坑 1：Server 启动失败但没有明显报错

症状：配置写好了，但 AI 调用工具时报"tool not found"。

原因：本地 Server 的依赖没装。比如 npx @playwright/mcp@latest 需要先有 Node.js 环境。

解决：先在终端手动运行启动命令，看有没有报错。确认能跑再写进配置。

坑 2：远程 Server 认证失败

症状：Server 显示已连接，但调用任何工具都返回 401。

原因：Token 过期或者格式不对。有的服务要 Bearer xxx，有的只要 xxx。

解决：仔细看官方文档的认证格式，别猜。

坑 3：多个 Server 名字冲突

症状：配置了两个 Server，但 AI 只能调用其中一个。

原因：两个 Server 暴露的工具名相同，AI 分不清调哪个。

解决：给每个 Server 起不同的名字，确保工具名不冲突。

坑 4：工具太多导致 AI 选择困难

症状：配了 10+ 个 MCP Server，AI 有时会调错工具。

原因：可用工具太多，AI 的上下文窗口被工具描述占满了，反而影响判断。

解决：只激活当前任务需要的 Server，不用的先关掉。质量比数量重要。

坑 5：本地 Server 占用端口

症状：重启后 Server 起不来，报端口被占用。

原因：上一次的 Server 进程没有正常退出。

解决：lsof -i :端口号 找到进程，kill 掉再重启。或者配置不同的端口。

总结

MCP 协议解决的核心问题：让 AI Agent 从"只能聊天"变成"能干活"。

3 条实操经验：

1. 先从 1-2 个 Server 开始。别一上来就配十几个，先把最常用的（比如文档系统）跑通，再慢慢加。

2. 本地 Server 先手动测试。依赖装好、命令跑通再写进 mcp.json，省得调试半天不知道哪里出了问题。

3. 多工具串联是杀手锏。单个 MCP Server 只是"让 AI 能用一个工具"，多个 Server 串联才是"让 AI 完成一个完整工作流"。

---

你用过 MCP 吗？在配置或使用中遇到过什么问题？评论区聊聊。