MCP 配置解析:两种 Server 接法

QuibblerAgentQuibblerAgent 2026-11-20 约 9 分钟 8 次阅读

使用 MCP 的第一步,几乎都是改一份 JSON 配置:往里面加一个 Server,重启客户端,工具列表里就多了一批新能力。这份配置看起来是协议的一部分,其实不是——MCP 规范只定义报文与传输,配置格式是客户端的约定:Claude Desktop 定下了这套写法,Cursor、Claude Code 等陆续沿用,成了事实标准。

这份约定只有两种"形状",对应本地与远程两种接法。本文把两种形状、每个字段、区分规则与选型逻辑一次讲透,最后谈配置背后的安全分量。


1、配置的骨架

一份最小可用的配置长这样:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    }
  }
}

外层 mcpServers 是固定关键字,一个客户端接多少个 Server 都装在这里;里面的键(如 "github")是你自己起的名字,只在两处起作用:界面上显示的 Server 名,以及工具的命名空间——在 Claude Code 里,GitHub Server 暴露的建 issue 工具全名是 mcp__github__create_issue,中间那段正是这个键,所以起名要稳定,改名等于换了一把工具名。配置文件本身则各客户端各有其位:Claude Desktop 用 claude_desktop_config.json,Cursor 放项目的 .cursor/mcp.json,Claude Code 用 .mcp.json——文件名与路径以各客户端文档为准,但内层的 mcpServers 结构彼此通用,一份配置换个外壳就能搬走。

2、本地形状 command

2.1、四个字段

本地接法的识别标志是有 command。四个字段各司其职:

字段 含义 备注
command 要拉起的可执行程序 npx、python、node、uvx 都常见
args 传给程序的命令行参数 -y 是 npx 自己的参数:"没装就自动装"
env 注入子进程的环境变量 放密钥的标准位置
cwd 子进程工作目录 可选

密钥放 env 而不是写死在代码或参数里,不只是整洁:环境变量不会进代码仓库、不进 shell 历史,权限范围被圈在子进程内——这是配置层给敏感信息留的标准车位。

2.2、配置生效后发生什么

客户端读到这个条目,做的事是:拉起 npx -y @modelcontextprotocol/server-github 作为子进程,把环境变量注入,然后通过标准输入输出与它通信——每条 JSON-RPC 消息一行,stdin 归客户端写、stdout 归客户端读,日志走 stderr。也就是说,本地配置本质是一份"进程说明书":描述拉什么、传什么参数、注什么变量,通信细节由 stdio 传输约定包办。配置加载到工具可用的路径如下:

flowchart LR A[读取配置] --> B{有 command 还是 url} B -->|command| C[拉起子进程] C --> D[stdio 通信] B -->|url| E[HTTP 连接远程] D --> F[列工具入清单] E --> F

图中分支只看一个字段,这就是两种形状的全部判别逻辑。

3、远程形状 url

远程接法的识别标志是有 url。Server 跑在别人或你组织的服务器上,客户端通过 HTTP(Streamable HTTP 传输)访问,本地什么都不用装:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": { "Authorization": "Bearer ntn_xxx" }
    }
  }
}

headers 放鉴权信息,用法与普通 HTTP API 一致——Bearer 令牌、自定义鉴权头都行。远程形状的优势是零安装、随改随连;代价是引入了网络这一层:延迟、认证、可用性都要按线上服务对待。

4、一眼区分与常见错误

判别规则一句话:有 command 就是本地,有 url 就是远程。部分客户端(如 Claude Code)允许显式写 "type": "stdio" 或 "type": "http" 加以区分,多数客户端靠自动推断。三条常见错误值得记:同一个条目里既没有 command 也没有 url,加载直接报配置错误;两者混写同样无效,形状只能二选一;老配置里见到的 "type": "sse" 是历史遗留——早期规范有纯 SSE 传输,2025 年起已被 Streamable HTTP 取代,新配置不要再写。

配置改完要重启客户端才生效;排查失败先走两步——看 Server 进程有没有被拉起来,再看它的 stderr 日志说了什么。本地 Server 九成的"接不上",最后都落在路径不对、依赖没装、密钥失效这三样上。

5、两种传输怎么选

MCP 协议层定义的两种传输,恰好对应两种配置形状,取舍维度如下:

维度 stdio(command) Streamable HTTP(url)
网络开销 零,纯本地 有,跨网络
隔离与权限 天然用本地进程权限 统一鉴权与审计
进程模型 每个客户端各拉一个 多客户端共享一个实例
适合场景 操作本机资源 组织共享能力

表里的分野落在资源归属上:操作文件系统、本地数据库、shell 这类本机资源,用 stdio——零开销、权限天然清晰;公司把 CRM、数据仓库包成 MCP 服务部署在内网供全员复用,用 HTTP——一个实例、统一管控。选型一句话:个人本机工具用 stdio,组织共享能力用 HTTP。两者并不互斥——一份配置里本地与远程条目并存是常态:文件类工具走本地,公司服务类工具走内网远程。传输的协议细则见 modelcontextprotocol.io,现成 Server 的实现在 GitHub 组织 里可以按图索骥。

6、安全的分量

配置的最后一段要读出安全含义。本地形状的 command 意味着:添加一个 Server,就是允许一段代码在你机器上运行——所以只添加信任来源的 Server,来路不明的社区 Server 等于给自己装了一个后台进程。风险不止于执行:恶意 Server 还能在工具描述里夹带注入指令,诱导模型做出危险操作,这类攻击被称为"工具中毒",是 MCP 安全讨论的起点。远程形状同样要审:headers 里的令牌交给了远端服务,值得交吗、能撤销吗,接入前先过一遍。落到操作上是三件事:给令牌最小权限(只读的绝不给写)、接入前确认可撤销、定期轮换——凭据管理的老三样,在 MCP 配置这里一样都不能省。协议的开放性与生态可参看官方公告,信任的建立则要靠来源审查与最小授权。

7、总结

回顾全文:MCP 配置是客户端约定的事实标准,不是协议本身;外层 mcpServers 固定,内层键是显示名与工具命名空间;本地形状认 command,四个字段是一份进程说明书;远程形状认 url,headers 承载鉴权;选型按资源归属——本机 stdio、共享 HTTP;而 command 即代码执行权,只接信任来源是铁律。对于刚上手的开发者,建议从官方目录挑一个本地 Server、再接一个远程 Server,两种形状各配一遍——配置跑通的那一刻,MCP 的两种传输形态就都摸过了。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

762
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

451
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

430