Agent MCP 完全指南

更新时间：2026-07-20。基于 MCP 官方文档（modelcontextprotocol.io）、MCP 2025-11-25 latest specification、Anthropic 原始公告、OpenAI Apps SDK、OpenAI MCP / Connectors、Codex MCP 和 Claude Code MCP 文档整理。

一、什么是 MCP

MCP（Model Context Protocol）是 AI 应用连接外部系统的协议层。它不是模型，不是某个具体工具，也不是 API 的替代品。

它解决的是 Agent 使用外部能力时的标准化问题：能力如何被发现，参数如何描述，请求如何传输，结果如何裁剪，权限边界如何确认。

MCP 背后通常仍然是 API、数据库、本地命令、文件系统或者 SaaS。区别在于，这些底层能力先被 MCP Server 包装成 Tools、Resources、Prompts，再由 Host 以可控方式交给模型使用。

这张图里最重要的是“模型不直接碰外部系统”。模型会提出工具调用意图，Host 决定是否允许和如何展示，Client 负责按 MCP 协议把请求发出去，Server 才去调用真实系统。
这样做不是为了多绕一层，而是把工具发现、参数契约、权限确认和结果裁剪放到更清楚的边界里。

二、为什么需要 MCP？

没有 MCP 时，每个 AI 客户端都要分别适配每个外部系统。一个客户端想接 GitHub、Notion、数据库和本地文件，就要各做一套连接；另一个客户端也想接这些系统，又要再做一遍。

系统越多、客户端越多，集成关系就会变成一张很难维护的网。

MCP 想把这个问题收敛成更稳定的结构：

AI 客户端支持 MCP
外部系统提供 MCP Server
双方按同一套协议通信

它不保证所有集成都零成本，但至少让“AI 如何发现工具、如何传参数、如何读取上下文”变成可复用的协议，而不是每个产品各写一套私有适配。

所以 MCP 的价值不只是“让模型能调工具”，更准确地说是四件事：

可发现：Server 能告诉客户端自己有哪些能力。
可描述：工具参数可以用 JSON Schema 表达。
可复用：同一个 Server 可以被不同 AI Host 连接。
可治理：Host 可以围绕工具调用做确认、审计和限制。

三、从一次工具调用理解 Host、Client、Server

理解 MCP 最好的入口不是背协议方法，而是看一次工具调用到底经过哪些角色。

假设用户说“帮我查最近错误日志”，模型本身并不会直接访问日志平台。它只能判断“这个任务需要查日志”。真正把请求送到日志系统的是 Host、Client 和 Server 共同完成的链路。

角色	可以怎么理解	主要责任
Host	用户正在使用的 AI 应用	管用户输入、模型调用、工具展示、权限确认、上下文组织
Client	Host 内部连接某个 Server 的协议会话	发起初始化、列出能力、调用工具、读取资源
Server	外部系统的 MCP 适配器	把 API、数据库、文件系统、SaaS 包装成 MCP 能力

Host 是 AI 应用本身，例如 Claude Desktop、Claude Code、Cursor、VS Code、ChatGPT 或 Codex。用户是在 Host 里输入需求，模型也是由 Host 调用，工具是否展示、是否需要确认、返回结果如何放回上下文，也都由 Host 组织。

Client 是 Host 内部负责连接某个 MCP Server 的协议会话。一个 Host 可以同时连多个 Server，所以通常也会有多条 Client 会话。

Server 是外部系统的适配器。它把真实系统包装成 MCP 能理解的能力入口。Server 背后可以是 HTTP API、数据库、本地命令、文件系统，也可以是 Notion、GitHub、Slack 这类 SaaS。

如果把这三层混在一起，就很容易误以为 MCP 只是本地脚本，或者误以为模型能绕过 Host 直接访问外部系统。

用 GitHub PR 看懂 Server、MCP、App 和 Connector

假设用户在 Codex 或 ChatGPT 中说：“读取 acme/payments 仓库的 PR #123，概括改动并指出是否有风险。”先看一个不依赖产品化 App 或 Connector 的最小 MCP 链路：

Host 把用户请求交给模型。模型根据 GitHub MCP Server 通过 tools/list 暴露的工具，选择一个读取 PR 的工具。
Host 内部的 Client 按 MCP 协议向 Server 发送 tools/call。
GitHub MCP Server 接收请求，校验参数，再调用 GitHub REST API 或 GraphQL API。
Server 把 GitHub 返回的数据裁剪成 tool result，交回 Host；Host 再把结果放回模型上下文，并向用户展示摘要。

下面两个请求分别属于不同层。工具名和参数只是示例，真实字段以该 Server 的 tools/list 结果为准。

MCP Client 发给 GitHub MCP Server 的请求：

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "get_pull_request",
    "arguments": {
      "owner": "acme",
      "repo": "payments",
      "pull_number": 123
    }
  }
}

Server 内部发给 GitHub API 的请求：

GET /repos/acme/payments/pulls/123 HTTP/1.1
Host: api.github.com
Authorization: Bearer <github-token>

这两个请求说明了四个名词分别指什么：

名词	在 GitHub PR 例子中是什么	所在层
MCP Server	接收 `tools/call`、执行校验和业务逻辑、调用 GitHub API 的程序	运行组件
MCP	规定 Host/Client 与 Server 如何发现工具、传输 JSON-RPC 消息和返回结果的协议	通信协议
App（OpenAI Apps SDK 语境）	ChatGPT 中由 MCP Server 支撑的集成；MCP Server 必需，Web Component/UI 可选。发现、安装、提交和发布属于外层 Plugin	产品集成
Connector（需要注明产品语境）	不是 MCP 协议角色。Responses API 中是 OpenAI 维护、通过 `connector_id` 使用的 MCP 包装层；ChatGPT 旧文档中则是后来改称 App 的连接入口	产品术语

在 OpenAI 当前的 Plugin 模型中，Plugin 是用户发现、安装、提交和发布的包，App 是 Plugin 内部由 MCP 支撑的能力。从用户视角看，App 是可以启用和使用的完整集成；从开发结构看，它至少需要 MCP Server，UI 则是可选增强。因此 App 不是另一个和 Server 并列的服务器。MCP Apps 是用于返回和渲染交互式 UI 的可选协议扩展，二者有关联，但不在同一层。

“Connector”不是 MCP 规范里的通用角色，它的含义要看具体产品。ChatGPT 已在 2025-12-17 把原来的 connectors 统一改名为 apps；当前 ChatGPT 文档和界面使用 “App”，data-only App（纯数据 App）即使没有 UI 也仍然是 App。Responses API 则继续使用 “Connector” 这个名称，专指 OpenAI 维护、通过 connector_id 选择的 MCP 包装层。也就是说，App 和 Connector 不是需要同时放进调用链的两个新组件，而是不同产品界面的集成名称。

因此，在解释 MCP 协议角色时，不要把链路固定画成“Host → App → Connector → MCP Server”。基础链路仍然是 Host 内的 Client → MCP Server → 外部 API；App 和 Connector 描述的是产品如何包装或提供这条能力，不是两个必经的协议跳点。

两段连接，可能是两套 token

GitHub PR 例子里至少有两段独立连接。不要因为它们出现在同一次用户操作里，就假设它们一定共用一个 token。

连接	传输和用途	可能使用的凭据	凭据由谁校验
Host / Client → MCP Server	`stdio` 或 Streamable HTTP；发送 MCP 的 JSON-RPC 请求	远程连接可用 Bearer Token、API Key 或 OAuth access token；本地 `stdio` 通常没有 HTTP token	MCP Server 或前置网关
MCP Server → GitHub API	普通 HTTPS REST/GraphQL 请求；读取 PR、评论或修改标签	GitHub OAuth token、Personal Access Token、GitHub App installation token 等	GitHub API

两段凭据可能由不同系统签发，audience、scope、生命周期和存储位置也可能不同。安全实现应默认把它们当作两套授权边界，不能把发给 MCP Server 的 token 未经校验地转发给 GitHub API。这里的“两套 token”不是说每种实现都必须出现两个 token 字符串：本地 stdio 连接的第一段通常就没有 HTTP token。

直接 MCP 接入不需要 App 或 Connector

如果只想让一个 Host 调用远程 GitHub MCP Server，可以直接配置 MCP endpoint：

静态接入：在 Host 配置中填写 URL，并通过 Authorization: Bearer ...、API Key 或其他约定的 header 传递凭据。
OAuth 接入：支持该能力的 Host 按 MCP 授权流程完成登录和授权，再携带 access token 调用 Server。
本地接入：Host 通过 stdio 启动 Server，Server 再从环境变量、凭据存储或自己的 OAuth 流程取得访问 GitHub 的凭据。

这些都是直接 MCP 集成，协议上不要求先注册成 ChatGPT App，也不要求使用 Responses API Connector。App / Connector 不是 MCP 连接或认证的必需层。围绕它们的产品可以提供安装和启用、工具展示、可选 UI、账号连接、授权同意、管理员策略和审计；具体有哪些能力取决于 Host。

“Connector”也不等于“自动完成 OAuth”。例如 OpenAI Responses API 中，远程 MCP 使用 server_url，Connector 使用 connector_id；Connector 不是 OAuth 服务器，OAuth 客户端注册和授权仍由接入应用完成，access token 再通过 authorization 传入。ChatGPT App 可以提供由 Host 承载的账号连接体验，但那是另一种产品实现。token 的签发、刷新和撤销最终仍由授权服务器与具体接入应用负责。

四、本地和远程只是部署形态

MCP Server 可以运行在本地，也可以运行在远端。本地和远程不是 MCP 与 API 的区别，只是 Server 部署在哪里、用什么传输方式通信。

形态	常见传输	适合场景	主要风险
本地 MCP Server	`stdio`	本地文件、代码仓库、浏览器自动化、开发环境	以当前用户权限运行，可能读写本机文件或执行命令
远程 MCP Server	Streamable HTTP、HTTP/SSE	SaaS、企业内部系统、团队共享工具	OAuth、token scope、审计、限流、数据出境

本地 MCP Server 通常由 Host 启动为一个子进程，通过 stdio 交换 JSON-RPC 消息。它简单直接，但也意味着 Server 本质上是在本机运行代码，权限往往接近当前用户。

远程 MCP Server 更像一个独立 HTTP 服务，可以服务多个客户端，但也必须处理 OAuth、token scope、审计、限流和数据出境问题。

因此，“MCP 是本地的，API 是远程的”这个说法不对。MCP 和 API 都可以本地，也都可以远程。真正的分界是：API 是底层程序接口，MCP 是 AI 使用这些接口的协议层。

五、协议分层应该怎么理解？

MCP 的协议可以拆成两层看。

Transport Layer 关心消息怎么传，例如本地用 stdio，远程用 Streamable HTTP。
Data Layer 关心消息说什么，例如初始化连接、列出工具、调用工具、读取资源、获取提示词模板。

这个分层的好处是：同一套 MCP 语义可以跑在不同传输方式上。本地 Server 和远程 Server 的连接方式不同，但上层仍然可以使用相同的 initialize、tools/list、tools/call、resources/read 这类方法。

连接开始时，Client 会先和 Server 进行初始化。初始化不是形式主义，它让双方先确认协议版本、声明能力，再进入正常调用阶段。

一个 Server 可能只支持工具，也可能同时支持资源和提示词；一个 Client 可能支持 roots、sampling、elicitation，也可能只支持最基本的调用。能力协商的目的，就是让后续调用建立在明确契约上。
学习 MCP 时不需要一开始就背每个 JSON 字段。更有用的是先看清生命周期：先初始化，后协商能力，再进入工具、资源和提示词调用阶段。

六、Server 暴露的不是 API 目录

MCP Server 暴露的核心能力通常分成三类：Tools、Resources、Prompts。它们不是三个随便起的名字，而是代表了 AI 使用外部系统时的三种不同需求。

能力	含义	例子	设计重点
Tools	可执行动作	查询数据库、创建 issue、触发构建、发送消息	说明副作用、参数契约和失败恢复方式
Resources	可读取上下文	文件内容、数据库 schema、日志片段、文档页面	控制范围、裁剪内容、避免泄露敏感信息
Prompts	可复用提示词模板	`review_pr(pr_number)`、`write_release_note(version)`	把常见工作流包装成可选入口

Tool 的关键不是函数名，而是清楚的描述和参数契约。模型能不能正确调用，很大程度上取决于工具描述是否说明了使用场景、参数含义和副作用。

Resource 和 Tool 的区别可以这样记：Resource 是“给模型看的东西”，Tool 是“让模型做的动作”。
读 README 是 Resource，创建 PR 是 Tool；读数据库 schema 是 Resource，执行 SQL 查询是 Tool。
Prompts 更像 Server 提供的工作流入口。用户可以主动选择这些模板，让 Host 把它们组装到模型上下文里。

真正设计 MCP Server 时，最重要的不是把底层 API 全部搬出来。把 get_user、list_orders、get_invoice、list_refunds 全部扔给模型，通常不如提供一个 summarize_customer_billing_status(customer_id)。

前者是在复刻 API 目录，后者才是在提供面向任务的工具。

七、Client 也可以提供能力

很多入门文章只讲 Tools、Resources、Prompts，这容易让人误以为 MCP 是单向的。实际上，Client 也可以在能力协商时声明自己支持的能力。

官方规格里常见的 Client features 包括 Roots、Sampling、Elicitation。

Client 能力	解决什么问题	注意点
Roots	告诉 Server 当前应该关注哪些文件系统范围	Roots 是范围提示，不是强安全边界，真正隔离仍要靠权限和沙箱
Sampling	允许 Server 通过 Client 请求一次模型生成	Client 应该控制模型选择、权限、提示词审查和返回结果
Elicitation	允许 Server 结构化地向用户补充信息	适合确认偏好、补字段、审批操作，不适合索要密码或 API key

Roots 常见于代码仓库和本地文件场景。它告诉 Server 当前工作区在哪里，帮助 Server 少扫无关文件。但它不是安全沙箱，恶意 Server 不会因为看见 roots 就自动变安全。
Sampling 让 Server 可以请求 Client 代它调用模型。例如一个旅行 MCP Server 已经查到了 47 个航班，它可以请求 Client 让模型帮忙排序。
Elicitation 是 Server 向用户要结构化输入的机制。例如预订酒店前补充房型、是否购买保险、是否确认支付。

这几个能力的共同点是：Server 可以请求，Client 负责展示、确认、过滤和返回。

2025-11-25 规范还补充了 sampling 里的 tools 和 toolChoice，也就是 sampling 内部也可以有工具调用循环。
2025-11-25 规范增强了枚举 schema，并加入 URL mode elicitation。

八、一次工具调用应该怎么看？

还是用“查最近错误日志”这个例子。一个好的理解方式不是记住十二个协议步骤，而是看懂责任边界。

这条链路可以压缩成五步：

用户提出任务。
模型判断需要使用日志工具。
Host 展示工具名、参数和必要的确认信息。
Client 调用对应 MCP Server。
Server 调底层日志 API，并把裁剪后的结果返回给 Host。

这说明了 MCP 的一个核心安全前提：模型不应该直接拥有外部系统权限。

模型可以提出工具调用意图，但真实动作应该被 Host 和 Server 包在明确边界里。这样用户才有机会看到即将调用什么工具、带什么参数、可能产生什么影响。

九、MCP 和 API、Function Calling、Skill、Plugin 的关系

MCP 经常和 API、Function Calling、Skill、Plugin 混在一起讨论，但它们处在不同层。

概念	所在层	作用	和 MCP 的关系
API	底层系统能力	给程序调用真实系统	MCP Server 经常包装 API
Function Calling	模型 API 工具调用机制	让模型输出结构化 tool call	Host 可把 MCP tools 转成模型工具 schema
Skill	Agent 工作说明	告诉 Agent 什么时候用能力、怎么拆任务	Skill 教 Agent 怎么做，MCP 提供真实入口
Plugin	分发容器	打包 skills、commands、hooks、MCP Server、assets	MCP Server 可以是 Plugin 的一部分

API 是底层系统能力。例如 GitHub API、数据库接口、内部 RPC、DataPilot 查询接口，都属于系统给程序调用的接口。MCP 可以包装 API，但不是替代 API。

Function Calling 是模型 API 层的工具调用机制。实际运行时，Host 可能先从 MCP Server 拉到工具定义，再转成模型 API 能理解的 tool schema；模型产生 tool call 后，Host 再把它转回 MCP 的 tools/call。

Skill 是给 Agent 的工作说明。一个常见组合是：Skill 负责教 Agent 怎么做，MCP Server 负责提供工具，底层 API 或 CLI 负责真正执行。

Plugin 是分发容器。它可以打包 skills、commands、agents、hooks、MCP Server、bin、docs、assets 等内容。MCP Server 只是 Plugin 能包含的一类能力，不等于 Plugin 本身。

所以这几层可以这样放：Plugin 负责分发，Skill 负责方法，MCP 负责工具协议，API/CLI/DB 负责真实执行。

十、什么时候值得做 MCP？

不是所有脚本都应该 MCP 化。一次性任务、个人临时脚本、只有一两个固定接口的场景，直接写脚本或者配一个 Skill 往往更轻。

当一个能力满足下面几条时，就开始值得考虑 MCP：

会长期给 Agent 使用。
希望多个 AI Host 都能复用。
需要工具发现、参数契约和结构化输出。
读写权限复杂，需要确认、审计、限流。
背后有多个 API、分页、字段裁剪、鉴权和错误恢复。
多人或团队共享，不只是个人临时自动化。

对企业内部系统尤其如此。内部日志平台、数据分析平台、工单系统、知识库系统，往往有复杂鉴权、分页、字段裁剪和权限边界。

如果直接把一堆 API 文档交给模型，模型既难选对接口，也容易把敏感数据带进上下文。把这些能力收口成任务级 MCP Tool，通常更适合 Agent 使用。

十一、设计 MCP Server 时要避免什么？

设计 MCP Server 可以先按下面这张清单检查：

原则	不推荐	更推荐
面向任务	暴露一堆底层 CRUD API	暴露能完成用户意图的任务级工具
读写分开	一个工具既预览又删除	`preview_delete_files` 和 `confirm_delete_files` 分开
输入结构化	让模型传一段自然语言	用 JSON Schema 写清类型、必填项、枚举和限制
输出可消费	返回一大段散文	返回稳定字段，并附简短摘要
错误可恢复	只返回 `failed`	说明原因和下一步，例如缺 scope、时间范围过大
结果要裁剪	把原始数据全塞回上下文	分页、摘要、字段过滤、脱敏

Tool 名也要稳定、清楚、少歧义。不要把多个副作用藏在一个泛泛的 execute 或 process 里，也不要让工具名和描述互相矛盾。

对高风险动作，最好拆成“预览”和“执行”两步。比如删除文件，不应该只有一个 delete_files(paths)；更好的设计是先 preview_delete_files(paths)，让用户看到影响范围，再用带确认信息的工具真正执行。

输入输出结构化不是形式主义。Agent 需要靠结构化字段继续调用后续工具，Host 也需要靠结构化元数据做展示、审计和权限判断。

十二、安全边界是 MCP 的核心问题

MCP 强大的地方在于它连接真实系统，危险也来自这里。本地 MCP Server 通常以当前用户权限运行，所以它可能读取本地文件、访问环境变量、执行命令，甚至删除数据。

远程 MCP Server 的风险不同。它可能接收模型上下文中的数据，也可能代表用户对外部服务执行动作。因此远程 Server 应该优先使用官方或可信来源，OAuth scope 应该最小化，高风险工具调用应该让用户确认，并且调用日志要可追踪。

风险	发生位置	缓解方式
Prompt injection	网页、issue、文档、日志、数据库内容	把 tool result 当数据，不当指令；高风险动作二次确认
Token passthrough	远程 Server / OAuth 代理	不接受未签发给 MCP Server 的 token，校验 audience 和 scope
Confused deputy	OAuth 代理型 MCP Server	做 per-client consent、redirect URI 精确校验、CSRF/state 保护
SSRF	OAuth metadata discovery、URL 处理	限制内网 IP、校验 redirect、生产环境要求 HTTPS
Session hijacking	Streamable HTTP / SSE 会话	不把 session 当认证，使用随机 session id，绑定用户身份
本地 Server 被替换或污染	本地安装、启动命令、依赖包	展示完整启动命令，限制权限，沙箱运行，优先可信来源
Scope 过大	OAuth 授权	初始最小 scope，按需增量授权，避免 `*`、`all`、`full-access`

Prompt injection 必须单独记住。工具返回的网页、issue、文档、日志、数据库内容，都可能包含恶意提示词。

简单说就是：Tool result 是数据，不是系统指令。工具结果里写“忽略之前规则”没有任何权限。
OpenAI 的 MCP / Connectors 文档也强调了同一件事：连接第三方 MCP Server 时，要信任服务来源，对敏感动作要求 approval，并记录和审查发送给第三方 Server 的数据。

十三、三种常见模式

本地上下文型 MCP

本地上下文型 MCP 最常见于文件系统、Git 和代码仓库。它的价值在于让 Agent 能读取项目文件、搜索代码、查看 diff 和理解配置。

它的风险在本地文件权限。因此应该尽量用 roots 限定目录，默认只读，写操作拆成预览和执行。

远程文档型 MCP

远程文档型 MCP 常见于 Notion、Wiki、Google Drive、知识库和文档系统。它适合搜索文档、拉取页面、创建笔记和汇总知识库。

它的风险主要在 OAuth scope、私有文档出境和文档内容里的 prompt injection。因此搜索和读取要分开，写入前要预览，用户要能看到将访问的文档范围。

数据分析型 MCP

数据分析型 MCP 适合 SQL 引擎、DataPilot、数仓和实验分析平台。它可以提交 SQL、查询任务状态、下载结果并生成摘要。

它的风险在 SQL 越权、大结果集和敏感数据泄露。比较稳的做法是：SQL 先审查，结果分页和脱敏，任务 ID 可追踪，下载和展示分开。

远程 MCP 的请求到底长什么样？

远程 MCP 不是把某个业务 API 的 POST 字段直接暴露给 Agent。标准层面，Streamable HTTP transport 规定客户端把 JSON-RPC message 作为 HTTP POST body 发到同一个 MCP endpoint，例如 https://example.com/mcp。

业务字段不会出现在统一的 HTTP 顶层字段里，而是进入 tools/call 的 params.arguments，具体字段由服务端通过 tools/list 返回的 tool schema 决定。

一个最小的远程 MCP HTTP 请求大致长这样：

POST /mcp HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25
Authorization: Bearer <token>
 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_data",
    "arguments": {
      "sql": "select 1"
    }
  }
}

这里的 Authorization 只是例子。MCP 官方规范规定了 transport、JSON-RPC 方法和能力协商，不规定每个企业网关必须用什么鉴权 header。

内部系统可能使用 Authorization、X-API-Key、x-ac-Authorization 或动态签名 header；这些属于接入方自己的认证约定。

连接建立时，客户端先发 initialize：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

初始化后，客户端通常先发现工具：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

服务端返回工具名、描述和 inputSchema。之后客户端才知道某个业务工具到底需要哪些参数：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query_data",
    "arguments": {
      "sql": "select 1",
      "limit": 100
    }
  }
}

所以“没有业务 POST 字段示例”本身不一定是 MCP 文档缺失。

MCP 官方文档只会给 initialize、tools/list、tools/call 这种协议消息；具体业务字段应该由 MCP Server 的 tool schema、产品接入文档或 tools/list 结果提供。如果一个内部 MCP 只给 endpoint 和鉴权 header，却不给工具清单、参数 schema、返回结构和错误样例，那么缺的是产品接入文档，不是 MCP 标准本身。

Codex 和 Claude Code 的配置差异

Codex 和 Claude Code 最容易混的是“配置文件字段”，不是 MCP 协议。两者最终都会把配置转成对 MCP endpoint 的 HTTP 请求，但配置语法不一样。

对比项	Codex	Claude Code
主配置位置	`~/.codex/config.toml`；受信任项目可用 `.codex/config.toml`	local/user 写入 `~/.claude.json`；project 写入项目根目录 `.mcp.json`
远程 HTTP server	TOML：`[mcp_servers.name]` + `url = "..."`	JSON：`"mcpServers": { "name": { "type": "http", "url": "..." } }`
transport 字段	不写 `type`；有 `url` 就表示 Streamable HTTP server	必须写 `type: "http"` 或 `type: "streamable-http"`；只有 `url` 没有 `type` 是错误配置
静态 header	`http_headers = { "Header" = "value" }`	`"headers": { "Header": "value" }`，或 CLI `--header "Header: value"`
从环境变量取 header	`env_http_headers = { "Header" = "ENV_NAME" }`	`.mcp.json` 的 `headers` 支持 `${VAR}` 展开
标准 Bearer token	`bearer_token_env_var = "TOKEN_ENV"`，Codex 写入 `Authorization`	通常写 `headers.Authorization`，或用 CLI `--header "Authorization: Bearer ..."`
动态 header	主要靠环境变量映射	`headersHelper` 可在连接时执行命令并输出 header JSON
OAuth	`codex mcp login <server>`；可配 `mcp_oauth_callback_port` / `mcp_oauth_callback_url`	`/mcp` 或 `claude mcp login <name>`；可配 callback、client、metadata URL、scope

同一个内部 MCP，在 Codex 里可以这样写：

[mcp_servers.datapilot]
enabled = true
url = "https://datapilot.baidu-int.com/mcp"
http_headers = { "x-ac-Authorization" = "Bearer-<token>" }

在 Claude Code 里则应改成 JSON 的 headers，并显式写 type：

{
  "mcpServers": {
    "datapilot": {
      "type": "http",
      "url": "https://datapilot.baidu-int.com/mcp",
      "headers": {
        "x-ac-Authorization": "Bearer-<token>"
      }
    }
  }
}

或者通过 Claude Code CLI 写入：

claude mcp add --transport http datapilot https://datapilot.baidu-int.com/mcp \
  --header "x-ac-Authorization: Bearer-<token>"

关键区别可以压缩成一句话：MCP 请求 body 是标准 JSON-RPC，业务参数由 tool schema 决定；Codex/Claude Code 差异主要在本地配置如何生成 endpoint、transport 和 headers。

官方依据：

MCP Streamable HTTP transport：https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
MCP lifecycle / initialize：https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
MCP tools/list 与 tools/call：https://modelcontextprotocol.io/specification/2025-11-25/server/tools
OpenAI Codex MCP 配置：https://developers.openai.com/codex/mcp
Claude Code MCP 配置：https://docs.anthropic.com/en/docs/claude-code/mcp

十四、Registry 和分发问题

随着生态变大，MCP Server 的分发也会变成问题。用户不能只靠复制一段启动命令来判断 Server 是否可信，也不能每个 Host 都自己维护一份 Server 列表。

官方 MCP Registry 就是为这件事准备的。它目前仍处于 preview 阶段，定位是公开 MCP Server 的集中元数据仓库。

Registry 里保存的不是 Server 代码本身，而是标准化元数据，例如：

Server 的唯一名称，例如 io.github.user/server-name
Server 在哪里，例如 npm 包、Docker 镜像、远程 URL
如何运行，例如命令行参数、环境变量
描述、能力和安装配置

Registry 使用类似反向 DNS 的命名空间，并通过 GitHub 账号或域名验证来证明发布者身份。这解决的是“这个 Server 是否来自它声称的来源”，不是“这个 Server 一定安全”。

企业内部私有 Server 通常不适合发布到公共 Registry。更合理的做法是自建私有 Registry 或内部 marketplace，并叠加权限、审计和安全扫描。

十五、Extensions、Apps 和 Tasks

MCP 还有 Extensions 机制，用来承载核心协议之外的能力。扩展通过初始化阶段的 capability negotiation 声明支持情况，双方都支持时才启用；不支持时应该优雅降级。

当前官方文档里值得注意的扩展方向有三类：

Authorization Extensions：补充核心授权规格之外的企业授权或机器到机器授权能力。
MCP Apps：让 MCP Server 在对话式客户端里展示交互式 UI，例如图表、表单、视频播放器。
MCP Tasks：用于长时间运行的异步任务，支持轮询、中途补充输入和持久化句柄。

这里的 MCP Apps 只表示 MCP 的 UI 扩展：工具元数据指向 UI Resource，支持该扩展的 Host 读取并渲染组件。它不改变上文的基本关系，也不意味着没有 UI 就不能直接使用 MCP。

这说明 MCP 不只是“工具调用协议”。它正在往更完整的 Agent 集成层演进：既有工具和上下文，也有 UI、授权、异步任务和生态分发。

但落地时要克制。Extensions 是可选能力，不应该作为基础互通的前提。一个 Server 如果提供 UI 增强，也应该给不支持 UI 的 Client 返回有意义的文本或结构化结果。

十六、2025-11-25 规范更新要点

MCP 官方当前 latest specification 是 2025-11-25。相对 2025-06-18，几个和实践最相关的变化是：

授权服务器发现增强，支持 OpenID Connect Discovery。
授权流程支持通过 WWW-Authenticate 做增量 scope consent。
Tools、Resources、Resource Templates、Prompts 可以暴露 icon 这类额外 metadata。
官方补充了 tool name guidance，强调命名稳定和清晰。
Elicitation 的 enum schema 更标准，支持单选、多选和 URL mode elicitation。
Sampling 新增 tools 和 toolChoice，支持 sampling 内的工具调用。
增加实验性的 Tasks，用于可轮询、可延迟取结果的长任务。
JSON Schema 2020-12 成为 MCP schema definitions 的默认 dialect。

对只理解概念的读者，这些不是第一优先级。对要实现 Server、接远程授权或设计企业内部 MCP 平台的人，这些更新需要认真看。

十七、核心结论

MCP 最容易被误解成三类东西：本地工具、API 替代品、插件系统。这三种理解都不准确。

更准确的定位是：MCP 是 AI Host 和外部系统之间的协议边界。Host 管用户体验和权限，Client 负责协议会话，Server 把外部系统包装成 Tools、Resources、Prompts。

临时个人自动化通常不需要 MCP，脚本或 Skill 更轻。长期稳定使用、跨客户端复用、需要权限控制和审计的外部能力，才是 MCP 更合适的场景。

十八、阅读索引

概念理解：

一、先把 MCP 放到正确的位置
三、从一次工具调用理解 Host、Client、Server
六、Server 暴露的不是 API 目录
九、MCP 和 API、Function Calling、Skill、Plugin 的关系
Server 设计：
十、什么时候值得做 MCP？
十一、设计 MCP Server 时要避免什么？
十二、安全边界是 MCP 的核心问题
十四、Registry 和分发问题
规范变化：
七、Client 也可以提供能力
十五、Extensions、Apps 和 Tasks
十六、2025-11-25 规范更新要点

十九、参考链接

MCP 官方：

MarkZ

探索