就学joinlearn.com
AI 工具教程12 分钟

MCP 是什么 + Claude Code 配置 MCP 服务器完整指南(2026 入门)

MCP 是什么?一句话:AI 的 USB-C 接口。本文用第一人称实测带你搞懂 Model Context Protocol 中文含义、为何重要,并手把手用 claude mcp add 给 Claude Code 配置 MCP 服务器,附 stdio/Streamable HTTP、local/project/user scope、Windows cmd /c 踩坑全记录。

d
dfkai
作者
MCPClaude CodeModel Context ProtocolAI AgentMCP配置

MCP 是什么?一张图看懂 AI 的 USB-C 接口

MCP 是什么?一句话:MCP(Model Context Protocol,模型上下文协议)就是 AI 的 USB-C 接口——一个让大模型用统一标准插上各种外部工具、数据库、API 的开放协议。claude code mcp 配置 之所以这么火,就是因为配好一次,Claude 就能直接读你的 GitHub、查你的 Postgres、看 Sentry 报错,而不用你一段段往对话框里粘。

TL;DR:MCP 已于 2025-12-09 捐给 Linux 基金会旗下的 Agentic AI Foundation,成为跨工具通用层。给 Claude Code 加 MCP 只要一行 claude mcp add;远程服务用 Streamable HTTP、本地脚本用 stdio;配置分 local / project / user 三档;Windows 上 npx 类 stdio server 常踩 cmd /c 的坑。这篇我把自己实测的命令、终端 log 和翻车经历全摆出来。

我是 dfkai,日常重度使用 Claude Code、Cursor、各种 Agent。Model Context Protocol 中文 资料这两年很碎,版本变化又快,所以这篇我只写我亲手跑通的部分,核对了官方文档再下笔。本文是 用 AI Agent 从零做一个真实项目 系列的入门基石——MCP 是 Agent 接触真实世界的那只手。

MCP 作为 AI 与外部工具之间通用接口的架构图

为什么 MCP 重要?从"M×N 噩梦"到"M+N"

在 MCP 之前,每个 AI 应用要接每个工具,都得单独写一套对接代码。3 个模型 × 10 个工具 = 30 套胶水代码,这就是经典的 M×N 集成噩梦。

MCP 把它变成 M+N:工具方写一个 MCP Server,模型方实现一个 MCP Client,中间用统一协议对话。我实测的体感是:装一个 MCP server,Claude Code 立刻多出一批可调用的工具,零额外胶水代码。

2026 年还有一件大事值得知道:

  • 2025-12-09,Anthropic 把 MCP 捐给了新成立的 Agentic AI Foundation(AAIF),这是 Linux 基金会下的一个定向基金。MCP 与 Block 的 goose、OpenAI 的 AGENTS.md 一起成为创始项目;白金会员包括 AWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft、OpenAI。MCP 的技术方向仍由原维护者自主决定,基金会只提供中立治理(官方博客、Linux 基金会新闻稿)。

翻译成人话:MCP 不再是某一家的私货,而是行业默认的"通用层"。你现在学的配置方法,Cursor、VS Code、各种 Agent 框架都通用。这也是为什么我把它当成做 AI Agent 真实项目 的第一课。

MCP 的三个核心概念:Client / Server / Transport

动手前先把三个词理清,后面配置就不晕了:

概念角色例子
MCP Host / Client发起调用的一方,内置大模型Claude Code、Claude Desktop、Cursor
MCP Server提供工具/资源/提示的一方GitHub、Notion、Postgres、你自己写的脚本
Transport(传输)Client 和 Server 之间怎么通信stdio、Streamable HTTP

Transport 是新手最容易混的点,记住两条就够:

  • stdio:本地传输。Server 作为子进程跑在你机器上,通过标准输入输出通信。适合本地脚本、需要直接读本地文件/数据库的工具。
  • Streamable HTTP:远程传输。连云端服务(GitHub、Notion、Sentry 这类),官方现在的首选,支持 OAuth。老的 SSE 传输已被标记 deprecated,新项目别用了(以官方最新为准)。

配置 JSON 里写 type 时,streamable-http 是 http 的别名,从别人文档里复制过来不用改,这点官方 MCP 文档有明确说明。

MCP 一次工具调用的数据流时序图

怎么给 Claude Code 配置 MCP:claude mcp add 实操

这是本文核心。前提:已安装 Claude Code(claude --version 能跑出来)。所有命令我都在 macOS + Claude Code 实测过。

第一步:加一个远程 HTTP server(最常用)

远程服务一律走 Streamable HTTP。语法是 claude mcp add --transport http <名字> <url>。

# 基本语法
claude mcp add --transport http <name> <url>

# 我实测:接 Sentry,看线上报错
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 带 Bearer Token 的(比如 GitHub 远程 server)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

加完进 Claude Code 输入 /mcp,需要 OAuth 的服务会让你跳浏览器登录。我这边终端大致长这样(实测示意,以你环境为准):

$ claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Added HTTP MCP server sentry → https://mcp.sentry.dev/mcp (local scope)

# 进入 Claude Code 后
> /mcp
  MCP Servers
  ● sentry    connected   12 tools   (needs auth → press Enter to authenticate)

第二步:加一个本地 stdio server

本地脚本、数据库工具走 stdio。关键的命令顺序坑:所有 -- 开头的选项(--transport、--env、--scope)必须放在 server 名字前面,然后用 --(双横线)隔开后面真正要执行的命令。

# 基本语法:options 在前,-- 之后才是真正要跑的命令
claude mcp add [options] <name> -- <command> [args...]

# 我实测:接只读的 Postgres
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 带环境变量的(Airtable)
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

记不住顺序就背这句:"开关在前,双杠隔开,命令在后"。我刚开始就因为把 --scope 写到名字后面,被它当成 server 的参数传下去,报了一堆莫名其妙的错。

第三步:选对 scope(local / project / user)

这是团队协作的关键。三档作用范围完全不同(官方文档):

Scope在哪些项目加载是否随团队共享存储位置
local(默认)仅当前项目否~/.claude.json
project仅当前项目是,随 git 提交项目根目录 .mcp.json
user你所有项目否~/.claude.json
# 默认 local:只有你、只在这个项目
claude mcp add --transport http stripe https://mcp.stripe.com

# project:写进 .mcp.json,提交 git,全队共享
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# user:你个人所有项目通用(比如常用工具)
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

实测建议:个人调试用 local;团队要统一的工具用 project 提交到仓库;自己跨项目天天用的(比如笔记、浏览器自动化)放 user。

注意命名历史坑:旧版里 local 曾叫 project、user 曾叫 global,网上老教程的术语对不上是正常的,以现在的三档为准。当同名 server 在多档都定义时,优先级是 local > project > user > 插件 > claude.ai 连接器。

常用管理命令

claude mcp list            # 列出所有已配置 server
claude mcp get github      # 看某个 server 详情(含连接状态)
claude mcp remove github   # 删除
# 进入 Claude Code 内部:
/mcp                       # 看实时连接状态、工具数、做 OAuth 认证

如果你想从 Claude Desktop 把已配好的 server 一键导过来:claude mcp add-from-claude-desktop(仅 macOS / WSL)。

dfkai 实测踩坑:Windows 的 cmd /c 大坑

这是我看到最多人卡住的地方,单独拎出来讲。

现象:在 Windows 上用 npx 跑 stdio server(比如 Playwright MCP),server 死活 Failed to connect 或者卡住没反应,Mac/Linux 同样的配置却好好的。

根因:Windows 上的 npx 实际是 npx.cmd(一个批处理脚本),Node 的子进程 spawn 不会把它当可执行文件直接调起来,stdio 的标准输入输出管道接不上,于是协议握手静默挂死。社区里的修法有两类:

修法 A:用 cmd /c 包一层(很多老教程的写法,改 .claude.json 里的 server 配置)

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

修法 B(我更推荐,更稳):绕开 npx,直接用 node 指向 cli.js

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": ["C:\\path\\to\\@playwright\\mcp\\cli.js"]
    }
  }
}

直接 node 调 cli.js 跳过了 .cmd 批处理外壳,stdio 管道能正确连上,我帮 Windows 同事这样改一次就好了(参见 microsoft/playwright-mcp #1540、anthropics/claude-code #4793)。

其他高频坑:

  • spawn npx ENOENT:Node 不在 Claude Code 能看到的 PATH 上。新开一个终端跑 node --version、npx --version 确认;装了 Node 还报错就重启终端/电脑刷新 PATH。
  • 首次 OAuth 后 server 启动超时:启动前设 MCP_TIMEOUT=10000 claude 给它 10 秒。
  • WSL 里报 MCP server disconnected:确认 server 跑在 WSL 内的 Node 上,别跨 Windows/WSL 边界调路径。
  • 项目 scope server 一直 ⏸ Pending approval:出于安全,.mcp.json 里的 server 首次要你交互式批准,跑一次 claude(交互模式)确认即可;想重置批准用 claude mcp reset-project-choices。
  • MCP 工具输出过大警告:超过 1 万 token 会告警,默认上限 2.5 万,需要时 export MAX_MCP_OUTPUT_TOKENS=50000。

进阶:企业级私网访问(MCP Tunnels / Self-hosted Sandboxes)

2026-05 在 Code with Claude(伦敦)上,Anthropic 给 Claude Managed Agents 加了两个企业向能力,值得大陆做内网部署的团队关注(注意:这是 Managed Agents 的特性,不是 Claude Code CLI 的本地命令):

  • MCP Tunnels(研究预览):让 Agent 在不暴露公网的前提下访问私网里的 MCP server——你部署一个轻量网关,只发一条出站连接,无需开入站防火墙、无公网端点,流量端到端加密。内网数据库/API 接 Agent 的合规友好方案。
  • Self-hosted Sandboxes(公测):工具执行跑在你自己掌控的基础设施,或 Cloudflare、Daytona、Modal、Vercel 等托管沙箱上;Agent 的编排/上下文管理仍在 Anthropic 侧。

来源:Anthropic 官方博客、The New Stack、InfoQ。具体可用性以官方最新为准。

中文用户专属:大陆可用性与国产替代

  • 网络:claude mcp add 本身没问题,但连 GitHub / Notion / Sentry 这类远程 HTTP server 需要稳定的国际网络;Claude Code 登录与模型调用也同理。本地 stdio server(自己写的脚本、本地数据库)不依赖外网,这是大陆用户更友好的路线。
  • 国产模型替代:MCP 是协议层,与模型解耦。理论上任何支持工具调用的客户端都能接 MCP;如果你用 DeepSeek 或其他 国产大模型,可以自己写 MCP Client 或用兼容框架对接同一批 MCP Server,工具复用、模型可换。
  • 成本:Claude Code 走订阅或 API 计费。MCP 本身不额外收费,但工具返回的大段内容会吃 token——一次数据库 schema 查询轻松上千 token(实测示意,以你环境为准),所以 MAX_MCP_OUTPUT_TOKENS 和分页很重要。这块的省钱思路我在 上下文工程指南 里展开讲。
  • 中文踩坑:Windows 中文用户路径里若有中文/空格,node 指向 cli.js 的绝对路径要用引号包好,否则同样会 spawn 失败。

下一步:从用 MCP 到造 MCP

配会了别人的 server,自然会想"我自己的内部工具能不能也包成 MCP"。能,而且不难——用 Python 的 FastMCP 几十行就能起一个。我在 用 Python + FastMCP 自建 MCP Server 里手把手带你从零写一个、用 MCP Inspector 调试、再 claude mcp add 接进来闭环。

学习路径建议:

  1. 先会用(本文)→ 给 Claude Code 接 3 个现成 server 练手
  2. 再会造 → 自建 MCP Server
  3. 组队干活 → 配合 Claude Code 子智能体 / Agent Teams 让多个 Agent 共享同一批 MCP 工具
  4. 做真项目 → 用 AI Agent 从零做一个真实项目 把 MCP、上下文工程、子智能体串成完整工作流

如果你还没系统用过 Claude Code,建议先看 Claude Code 入门教程 打底。

想系统学 AI Agent + MCP 实战?

这篇是入门骨架。如果你想把 MCP、上下文工程、子智能体、RAG 一路打通,跟着做出能上线的真实项目,我把完整路径整理成了课程:

点此了解并立即订阅 →

FAQ

Q1:MCP 是什么?和插件(plugin)有什么区别? MCP 是一个开放协议标准,定义了 AI 模型如何统一调用外部工具/数据。插件通常是某个具体产品的私有扩展机制;MCP 是跨工具通用的——同一个 MCP Server,Claude Code、Cursor、VS Code 都能接。在 Claude Code 里,插件还能反过来打包内置 MCP server,两者可以结合。

Q2:claude code mcp 配置选 stdio 还是 Streamable HTTP? 连云端服务(GitHub、Notion、Sentry)用 --transport http(Streamable HTTP),支持 OAuth、最稳。跑本地脚本或要直接读本地文件/数据库,用 --transport stdio。老的 SSE 已 deprecated,新项目别用。

Q3:为什么我在 Windows 上配的 MCP server 连不上? 大概率是 npx 的 .cmd 批处理外壳导致 stdio 管道接不上。两个修法:在配置里用 cmd /c 包一层 npx;或更稳的做法——直接用 node 指向 server 的 cli.js 绝对路径,绕开 npx。同时确认 Node 在 PATH 上、路径里的中文/空格用引号包好。

Q4:Model Context Protocol 中文叫什么?现在归谁管? 中文一般译作"模型上下文协议"。2025-12-09 起,Anthropic 已把它捐给 Linux 基金会旗下的 Agentic AI Foundation 做中立治理,与 goose、AGENTS.md 同为创始项目,但技术方向仍由原维护者通过 SEP 流程自主决定——所以它已经是行业通用层,不是某一家说了算。

本文事实核对来源:Claude Code 官方 MCP 文档、MCP 官方博客(加入 AAIF)、Linux 基金会新闻稿、Anthropic Managed Agents 更新。命令与终端 log 为作者实测示意,以你本地环境与官方最新为准。

返回博客列表
分享文章：

相关文章

AI 工具教程

手把手开发你的第一个 MCP Server:Python/FastMCP 给 AI 接自定义工具(2026)

mcp server 开发完整教程:用 Python + FastMCP 从零写一个能调外部 API 的 MCP server,本地用 MCP Inspector 调试,再接进 Claude Code。含实测代码、调试日志、踩坑与大陆可用性。

12 分钟
AI 工具教程

用 AI 编程 Agent 从零做一个真实小项目:2026 端到端实战(不会编程也能做软件)

我用 AI 编程 Agent 从需求到上线做了一个真实小项目的全程实录:选工具、写需求、设计、AI 编码、调试、部署。不会编程也能做产品的 vibe coding 中文实战指南,含实测耗时与踩坑。

16 分钟

想要更深入的学习？

订阅我们的课程，获得完整的视频教程、源码资料和专属答疑支持

查看全部课程