如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

构建 MCP 服务器

为插件添加实时数据和可执行受控操作的工具。

如果插件的用例需要实时数据、身份验证、受控操作,或需要在您运维的基础设施上运行代码,请添加 MCP 服务器。服务器定义 ChatGPT 和 Codex 可以使用哪些工具,无需返回自定义 UI。

从用例清单中列出的受支持目标入手。每个工具都应帮助用户完成一个明确的目标,并且只提供实现该目标所需的数据和操作。

先构建工具。确认服务器可以在没有自定义 UI 的情况下正常运行后,您可以为需要可视化交互的工作流向 MCP 服务器添加 UI。

选择 MCP 软件开发工具包

官方软件开发工具包提供模式定义辅助工具、服务器脚手架,并支持可流式 HTTP 传输。

安装与您的服务器技术栈匹配的 SDK。

# TypeScript
npm install @modelcontextprotocol/sdk zod

# Python
pip install mcp

创建服务器

创建 MCP 服务器,并为其指定稳定的名称和版本号。

创建 MCP 服务器
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "acme-projects",
  version: "1.0.0",
});

MCP 服务器还可以在初始化期间返回 instructions 字段。ChatGPT 和 Codex 会结合这些指令与工具元数据使用工具。

在服务器指令中说明适用于多个工具的要求,例如工具必须按什么顺序调用,或哪些工具共用同一速率限制。将最重要的细节放在前 512 个字符内。不要逐一重复工具描述,也不要试图改变模型的个性。

添加服务器指令
const server = new McpServer(
  { name: "acme-projects", version: "1.0.0" },
  {
    instructions:
      "Before updating a project, call get_project to confirm its ID and current status.",
  }
);

根据用户目标定义工具

为插件必须支持的每项独立操作分别创建工具。优先使用 list_projects、get_project 和 update_project 这类功能明确的工具,避免把多个互不相关的操作模式放进同一个工具。

每个工具都需要具备以下要素。

  • 能体现操作的名称和便于理解的标题。
  • 说明何时使用该工具的描述。
  • 明确定义的输入模式。
  • 输出模式(当工具返回结构化数据时)。
  • 准确反映工具行为的安全注解。
  • 检查请求权限并执行操作的处理函数。

模型根据这些元数据决定是否调用工具以及如何调用。名称、描述、模式和注解都应视为插件面向用户的行为的一部分。

定义项目查询工具
// Local example data; replace this with your application data.
const projects = [
  { id: "project-1", name: "Website", status: "active" },
  { id: "project-2", name: "Launch", status: "archived" },
];
async function listProjects({ status }: { status?: string }) {
  return projects.filter((project) => !status || project.status === status);
}

import { z } from "zod";

server.registerTool(
  "list_projects",
  {
    title: "List projects",
    description:
      "Use this when the user wants to find or review projects in their Acme workspace.",
    inputSchema: {
      status: z.enum(["active", "archived"]).optional(),
    },
    outputSchema: {
      projects: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          status: z.string(),
        })
      ),
    },
    annotations: {
      readOnlyHint: true,
      openWorldHint: false,
      destructiveHint: false,
    },
  },
  async ({ status }) => {
    const projects = await listProjects({ status });

    return {
      structuredContent: { projects },
      content: [
        {
          type: "text",
          text: `Found ${projects.length} projects.`,
        },
      ],
    };
  }
);

在没有 UI 的情况下返回有用的结果

工具结果可以包含以下字段。

  • structuredContent 提供简明的数据,供模型查看并在后续调用中使用。
  • content 提供文本或其他 MCP 内容,帮助模型回应用户。
  • _meta 提供客户端专用的数据,对模型不可见。

返回足够的信息,让模型无需组件也能完成工作流。在结构化结果中使用稳定的标识符,以便后续调用的工具引用相同的记录。

不要在工具结果中包含机密信息、访问令牌或不必要的个人数据。_meta 中的数据对模型不可见。服务器仍需执行授权检查并安全存储数据。

验证请求身份并检查权限

如果工具会读取私有数据或代表用户执行操作,请添加身份验证。在 MCP 服务器上对每个请求强制执行授权检查,切勿依赖模型判断用户是否有访问权限。

有关 OAuth 发现机制、安全方案和授权质询,请参阅验证用户身份。

为了方便用户使用多个账户,请提供一个需要身份验证的只读工具,用于获取账户资料,并用 _meta["openai/profile"]: true 标记该工具。OpenAI 会根据账户资料以一致的方式识别已连接的账户,帮助用户区分它们。根据请求中已验证的凭据确定应返回哪个账户的资料,并将每次工具调用限制在相应凭据允许的范围内。即使没有账户资料工具,用户也可以连接多个账户。有关模式和实现示例,请参阅支持多个账户。

工具注解与引导式提取

根据工具的实际行为设置注解。

  • readOnlyHint 仅在工具无法更改状态时设为 true。
  • destructiveHint 在工具可能造成不可逆或难以撤销的后果时设为 true。
  • openWorldHint 在工具会访问公共互联网或访问范围不受限定的外部实体时设为 true。通过网页搜索等只读操作进行访问也属于这种情况。如果工具只能访问范围明确的私有账户或工作空间,即使服务托管在外部,也可以设为 false。

这些注解帮助 ChatGPT 和 Codex 选择适当的确认方式和安全措施。服务器仍需自行执行授权检查、验证和确认。

如果服务器需要原始工具调用中未提供的结构化信息,请使用 MCP 的引导式提取机制。只询问用户能够合理提供的信息。不要使用该机制收集机密信息或绕过正常的身份验证流程。

兼容企业知识功能

企业知识功能可以使用 MCP 服务器提供的只读工具。要让插件能够作为企业知识来源,请为 search 和 fetch 工具实现标准输入模式,并用 readOnlyHint: true 标记其他只读工具。

对于模型应引用的来源,请返回用户能够打开的绝对 URL。将内部文档标识符保存在结果的 id 字段中。有关所需的模式和结果结构,请参阅为 ChatGPT 和 API 集成构建 MCP 服务器。

在本地运行和测试

提供一个可流式 HTTP 端点(通常位于 /mcp),然后使用 MCP Inspector 检查该端点。

npx @modelcontextprotocol/inspector

在 Inspector 界面中选择 Streamable HTTP,然后输入 http://localhost:3000/mcp。

使用 Inspector 完成以下检查。

  1. 确认初始化成功。
  2. 检查服务器指令以及服务器声明可用的工具列表。
  3. 分别使用有代表性的输入和无效输入调用每个工具。
  4. 验证模式、结果、错误和注解。
  5. 确认服务器在访问私有数据和执行写入操作时强制执行授权检查。

然后将自定义 MCP 服务器连接到 ChatGPT,并测试用例清单中的直接请求、间接请求、边界情况请求和超出支持范围的请求。

部署端点

要提交插件供公开发布,请将 MCP 服务器部署到稳定且可公开访问的 HTTPS 端点。通过安全 MCP 隧道可以在 ChatGPT 中连接私有 MCP 服务器,但这种连接方式不符合公开提交的要求。

生产端点必须满足以下要求。

  • 支持 MCP 的可流式 HTTP 传输。
  • 能在稳定的 URL 上响应请求,该 URL 通常以 /mcp 结尾。
  • 满足插件工作流对延迟和可用性的要求。
  • 能访问所需的服务和数据存储。
  • 维持身份验证和授权边界。
  • 为初始化失败和工具调用失败生成日志和指标。

如果 MCP 服务器必须保持私有,请部署一个公共 HTTPS 代理,将 MCP 请求转发到私有服务器。使用 OpenAI 托管的 mTLS 验证 ChatGPT 作为 MCP 客户端的身份。如果插件需要验证用户身份,请使用 OAuth 2.1。如果您的网络要求使用 IP 允许列表,请采用已发布的 ChatGPT 连接器 IP 地址范围,并自动更新允许列表。使用 IP 允许列表时,仍需执行身份验证和授权检查。

公共端点必须保持可访问,以便进行插件审核和域名验证。公开提交时,不要仅使用安全 MCP 隧道,也不要使用临时隧道或本地端点。

选择基础设施

您可以将 MCP 服务器部署到无服务器平台、容器平台、边缘平台或传统应用基础设施上。选择平台时,请考虑以下因素。

  • 对运行时和依赖项的支持。
  • 平台如何处理流式响应。
  • 冷启动延迟和请求延迟。
  • 能否通过网络访问所需服务。
  • 数据驻留和合规要求。
  • 机密信息管理。
  • 日志记录、追踪和告警。
  • 对回滚和版本管理的支持。

如果服务器还托管可选的 UI 资源,请将这些资源部署到组件的内容安全策略允许的稳定来源上。

配置生产端点

部署前,请完成以下配置和检查。

  1. 通过托管平台的机密信息管理系统设置生产凭据。
  2. 配置授权服务器,并指定允许的重定向行为。
  3. 为资源开销大或操作对外部可见的工具设置超时和速率限制。
  4. 移除调试响应和不必要的个人数据。
  5. 确认日志中不含访问令牌或敏感的工具结果。

部署后,使用 MCP Inspector 调用生产端点。验证初始化过程、服务器指令、工具、模式、注解、身份验证、结果和错误。

规划更新

确保已发布的工具名称和模式保持向后兼容。添加字段或工具时,避免破坏现有接口约定。如果元数据发生变化,请刷新自定义 MCP 服务器连接,并在提交前重新运行整套评测用例。

如果插件提供可选 UI,当 HTML、JavaScript 或 CSS 的变更可能导致已缓存的组件无法正常工作时,请更新资源标识符的版本。

添加 MCP 扩展程序

OpenAI MCP 扩展程序可以将您的插件连接到 ChatGPT 的侧边栏、消息输入框和文件查看器。有关示例和设置方法,请参阅插件扩展程序。

安全提醒

  • 将所有工具输入视为不可信数据。
  • 在服务器上验证参数并强制执行授权检查。
  • 执行会产生重大影响的写入操作前,要求用户确认。
  • 不要在工具元数据或结果中包含机密信息和敏感数据。
  • 在日志中记录足够的上下文以便调查故障,同时避免记录凭据或不必要的个人数据。
  • 对资源开销大或对外部可见的操作实施速率限制。