如果插件的用例需要实时数据、身份验证、受控操作,或需要在您运维的基础设施上运行代码,请添加 MCP 服务器。服务器定义 ChatGPT 和 Codex 可以使用哪些工具,无需返回自定义 UI。
从用例清单中列出的受支持目标入手。每个工具都应帮助用户完成一个明确的目标,并且只提供实现该目标所需的数据和操作。
官方软件开发工具包提供模式定义辅助工具、服务器脚手架,并支持可流式 HTTP 传输。
安装与您的服务器技术栈匹配的 SDK。
# TypeScript
npm install @modelcontextprotocol/sdk zod
# Python
pip install mcp
运行 Ruby 示例时,请使用 Ruby 3.3,并安装 mcp(版本 1.10.0)、rackup(版本 2.3)和 webrick。将一个完整的服务器示例保存为 main.rb,然后运行 ruby main.rb。服务器会在 http://localhost:3000/mcp 监听可流式 HTTP 请求。
运行 Go 示例时,请使用 Go 1.26 或更高版本,并在您的 Go 模块中安装 github.com/modelcontextprotocol/go-sdk(版本 v1.8.0)。将一个完整的服务器示例保存为 main.go,然后运行 go run .。服务器会在 http://localhost:3000/mcp 监听可流式 HTTP 请求。
创建 MCP 服务器,并为其指定稳定的名称和版本号。
1
2
3
4
5
6import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "acme-projects",
version: "1.0.0",
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45package main
import (
"context"
"errors"
"fmt"
"github.com/modelcontextprotocol/go-sdk/mcp"
"log"
"net"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()
server := mcp.NewServer(&mcp.Implementation{Name: "acme-projects", Version: "1.0.0"}, nil)
handler := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return server }, &mcp.StreamableHTTPOptions{Stateless: true, JSONResponse: true})
mux := http.NewServeMux()
mux.Handle("/mcp", handler)
port := "3000"
listener, err := net.Listen("tcp", "127.0.0.1:"+port)
if err != nil {
log.Fatal(err)
}
httpServer := &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second}
fmt.Println("Listening on http://" + listener.Addr().String())
shutdownDone := make(chan struct{})
go func() {
defer close(shutdownDone)
<-ctx.Done()
shutdownCtx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
if err := httpServer.Shutdown(shutdownCtx); err != nil {
log.Print(err)
}
}()
if err := httpServer.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatal(err)
}
<-shutdownDone
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14require "mcp"
require "rackup"
require "rackup/handler/webrick"
server = MCP::Server.new(
name: "acme-projects",
version: "1.0.0"
)
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true, enable_json_response: true)
app = Rack::URLMap.new("/mcp" => transport)
Rackup::Handler::WEBrick.run(app, Host: "127.0.0.1", Port: Integer(ENV.fetch("PORT", "3000"))) do |http_server|
trap("INT") { http_server.shutdown }
trap("TERM") { http_server.shutdown }
end
MCP 服务器还可以在初始化期间返回 instructions 字段。ChatGPT 和 Codex 会结合这些指令与工具元数据使用工具。
在服务器指令中说明适用于多个工具的要求,例如工具必须按什么顺序调用,或哪些工具共用同一速率限制。将最重要的细节放在前 512 个字符内。不要逐一重复工具描述,也不要试图改变模型的个性。
1
2
3
4
5
6
7const 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.",
}
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45package main
import (
"context"
"errors"
"fmt"
"github.com/modelcontextprotocol/go-sdk/mcp"
"log"
"net"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()
server := mcp.NewServer(&mcp.Implementation{Name: "acme-projects", Version: "1.0.0"}, &mcp.ServerOptions{Instructions: "Before updating a project, call get_project to confirm its ID and current status."})
handler := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return server }, &mcp.StreamableHTTPOptions{Stateless: true, JSONResponse: true})
mux := http.NewServeMux()
mux.Handle("/mcp", handler)
port := "3000"
listener, err := net.Listen("tcp", "127.0.0.1:"+port)
if err != nil {
log.Fatal(err)
}
httpServer := &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second}
fmt.Println("Listening on http://" + listener.Addr().String())
shutdownDone := make(chan struct{})
go func() {
defer close(shutdownDone)
<-ctx.Done()
shutdownCtx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
if err := httpServer.Shutdown(shutdownCtx); err != nil {
log.Print(err)
}
}()
if err := httpServer.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatal(err)
}
<-shutdownDone
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15require "mcp"
require "rackup"
require "rackup/handler/webrick"
server = MCP::Server.new(
name: "acme-projects",
version: "1.0.0",
instructions: "Before updating a project, call get_project to confirm its ID and current status."
)
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true, enable_json_response: true)
app = Rack::URLMap.new("/mcp" => transport)
Rackup::Handler::WEBrick.run(app, Host: "127.0.0.1", Port: Integer(ENV.fetch("PORT", "3000"))) do |http_server|
trap("INT") { http_server.shutdown }
trap("TERM") { http_server.shutdown }
end
为插件必须支持的每项独立操作分别创建工具。优先使用 list_projects、get_project 和 update_project 这类功能明确的工具,避免把多个互不相关的操作模式放进同一个工具。
每个工具都需要具备以下要素。
- 能体现操作的名称和便于理解的标题。
- 说明何时使用该工具的描述。
- 明确定义的输入模式。
- 输出模式(当工具返回结构化数据时)。
- 准确反映工具行为的安全注解。
- 检查请求权限并执行操作的处理函数。
模型根据这些元数据决定是否调用工具以及如何调用。名称、描述、模式和注解都应视为插件面向用户的行为的一部分。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49// 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.`,
},
],
};
}
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77package main
import (
"context"
"errors"
"fmt"
"github.com/modelcontextprotocol/go-sdk/mcp"
"log"
"net"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
type listProjectsInput struct {
Status string `json:"status,omitempty"`
}
type project struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
}
type listProjectsOutput struct {
Projects []project `json:"projects"`
}
func main() {
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()
server := mcp.NewServer(&mcp.Implementation{Name: "docs-example", Version: "1.0.0"}, nil)
closed := false
mcp.AddTool(server, &mcp.Tool{
Name: "list_projects",
Description: "Use this when the user wants to find or review projects in their Acme workspace.",
InputSchema: map[string]any{"type": "object", "properties": map[string]any{
"status": map[string]any{"type": "string", "enum": []string{"active", "archived"}},
}},
Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true, OpenWorldHint: &closed, DestructiveHint: &closed},
}, func(_ context.Context, _ *mcp.CallToolRequest, input listProjectsInput) (*mcp.CallToolResult, listProjectsOutput, error) {
// Local example data; replace this with your application data.
projects := []project{{ID: "project-1", Name: "Website", Status: "active"}, {ID: "project-2", Name: "Launch", Status: "archived"}}
selected := []project{}
for _, p := range projects {
if input.Status == "" || input.Status == p.Status {
selected = append(selected, p)
}
}
result := &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("Found %d projects.", len(selected))}}}
return result, listProjectsOutput{Projects: selected}, nil
})
handler := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return server }, &mcp.StreamableHTTPOptions{Stateless: true, JSONResponse: true})
mux := http.NewServeMux()
mux.Handle("/mcp", handler)
port := "3000"
listener, err := net.Listen("tcp", "127.0.0.1:"+port)
if err != nil {
log.Fatal(err)
}
httpServer := &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second}
fmt.Println("Listening on http://" + listener.Addr().String())
shutdownDone := make(chan struct{})
go func() {
defer close(shutdownDone)
<-ctx.Done()
shutdownCtx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
if err := httpServer.Shutdown(shutdownCtx); err != nil {
log.Print(err)
}
}()
if err := httpServer.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatal(err)
}
<-shutdownDone
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68require "mcp"
require "rackup"
require "rackup/handler/webrick"
class ListProjects < MCP::Tool
tool_name "list_projects"
description "Use this when the user wants to find or review projects in their Acme workspace."
input_schema(
properties: {
status: {
type: "string",
enum: ["active", "archived"]
}
}
)
output_schema(
type: "object",
properties: {
projects: {
type: "array",
items: {
type: "object",
properties: {
id: { type: "string" },
name: { type: "string" },
status: { type: "string" }
},
required: ["id", "name", "status"]
}
}
},
required: ["projects"]
)
annotations(read_only_hint: true, open_world_hint: false, destructive_hint: false, idempotent_hint: nil)
def self.call(server_context:, status: nil)
# Local example data; replace this with your application data.
projects = [
{
id: "project-1",
name: "Website",
status: "active"
},
{
id: "project-2",
name: "Launch",
status: "archived"
}
].select { |project| status.nil? || project[:status] == status }
MCP::Tool::Response.new(
[
{
type: "text",
text: "Found #{projects.length} projects."
}
],
structured_content: { projects: projects }
)
end
end
server = MCP::Server.new(name: "docs-example", version: "1.0.0", tools: [ListProjects])
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true, enable_json_response: true)
app = Rack::URLMap.new("/mcp" => transport)
Rackup::Handler::WEBrick.run(app, Host: "127.0.0.1", Port: Integer(ENV.fetch("PORT", "3000"))) do |http_server|
trap("INT") { http_server.shutdown }
trap("TERM") { http_server.shutdown }
end
工具结果可以包含以下字段。
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 完成以下检查。
- 确认初始化成功。
- 检查服务器指令以及服务器声明可用的工具列表。
- 分别使用有代表性的输入和无效输入调用每个工具。
- 验证模式、结果、错误和注解。
- 确认服务器在访问私有数据和执行写入操作时强制执行授权检查。
然后将自定义 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 资源,请将这些资源部署到组件的内容安全策略允许的稳定来源上。
部署前,请完成以下配置和检查。
- 通过托管平台的机密信息管理系统设置生产凭据。
- 配置授权服务器,并指定允许的重定向行为。
- 为资源开销大或操作对外部可见的工具设置超时和速率限制。
- 移除调试响应和不必要的个人数据。
- 确认日志中不含访问令牌或敏感的工具结果。
部署后,使用 MCP Inspector 调用生产端点。验证初始化过程、服务器指令、工具、模式、注解、身份验证、结果和错误。
确保已发布的工具名称和模式保持向后兼容。添加字段或工具时,避免破坏现有接口约定。如果元数据发生变化,请刷新自定义 MCP 服务器连接,并在提交前重新运行整套评测用例。
如果插件提供可选 UI,当 HTML、JavaScript 或 CSS 的变更可能导致已缓存的组件无法正常工作时,请更新资源标识符的版本。
OpenAI MCP 扩展程序可以将您的插件连接到 ChatGPT 的侧边栏、消息输入框和文件查看器。有关示例和设置方法,请参阅插件扩展程序。
- 将所有工具输入视为不可信数据。
- 在服务器上验证参数并强制执行授权检查。
- 执行会产生重大影响的写入操作前,要求用户确认。
- 不要在工具元数据或结果中包含机密信息和敏感数据。
- 在日志中记录足够的上下文以便调查故障,同时避免记录凭据或不必要的个人数据。
- 对资源开销大或对外部可见的操作实施速率限制。