go-zero MCP 集成实战:基于官方 Go SDK 构建云原生 MCP Server
go-zero MCP 集成实战:基于官方 Go SDK 构建云原生 MCP Server
导读
本文围绕 go-zero 仓库中的 mcp/readme.md 展开,系统讲解如何借助 go-zero 的 REST 框架与官方 Model Context Protocol Go SDK,快速构建一个支持 SSE 与 Streamable HTTP 双传输、具备类型安全工具注册、Prompts、Resources 以及请求元数据桥接能力的 MCP Server。读完本文,你将掌握从配置、启动到工具注册与多租户元数据传递的完整实战方案,并理解 go-zero 是如何把 MCP 协议能力无缝嵌入其 REST Server 生态的。
MCP 与 go-zero 集成概览
Model Context Protocol(MCP)为 AI 应用(如 Claude、Cursor 等客户端)与外部数据源、工具之间提供了标准化的通信协议。go-zero 的 mcp 包正是为该协议提供的一等公民集成:它封装了官方 go-sdk),并复用了 go-zero 的 REST Server 与配置体系。
该包的核心设计目标体现在 mcp/readme.md 中:
- 官方 SDK 集成:底层完全构建在官方 MCP Go SDK 之上,协议兼容性由 SDK 保证;
- 无需直接导入 SDK:通过
mcp.AddTool()等包装函数,业务代码可以不显式 import 官方 SDK; - go-zero 无缝融合:配置结构直接内嵌
rest.RestConf,天然继承 go-zero 的配置加载、日志、超时与 CORS 体系; - 双传输支持:SSE(对应 2024-11-05 规范)与 Streamable HTTP(对应 2025-03-26 规范)可一键切换;
- 类型安全工具处理器:基于 Go 泛型 +
jsonschema标签自动生成 JSON Schema; - Prompts 与 Resources 完整支持;
- 请求元数据桥接:可选地在传输边界抽取 HTTP 请求元数据并注入 handler 的
context.Context。
安装依赖
在项目中引入 go-zero 即可,MCP 官方 SDK 作为传递依赖会被自动安装,无需在业务代码中直接导入:
go get github.com/zeromicro/go-zero
配置文件与参数详解
创建一个 config.yaml,mcp 包的配置类型为 McpConf,它内嵌了 go-zero 的 rest.RestConf(见 mcp/config.go),因此 name、host、port 等 HTTP 服务参数直接沿用 REST 服务的配置约定:
name: my-mcp-server
host: localhost
port: 8080
mcp:
name: my-mcp-server # MCP 服务器名(缺省时取顶层 name)
version: 1.0.0 # 版本,默认 1.0.0
useStreamable: false # false=SSE(默认),true=Streamable HTTP
sseEndpoint: /sse # SSE 端点,默认 /sse
messageEndpoint: /message # 消息端点,默认 /message
sseTimeout: 24h # SSE 连接超时,默认 24h
messageTimeout: 30s # 消息处理超时,默认 30s
cors:
- http://localhost:3000 # 允许的跨域来源
配置项速查表
以下字段及默认值均有源码依据(mcp/config.go),并与测试用例相互印证(mcp/server_test.go):
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name |
string | — | HTTP 服务名(必需,来自 RestConf) |
host |
string | — | 监听地址(必需,来自 RestConf) |
port |
int | — | 监听端口(必需,来自 RestConf) |
mcp.name |
string | 取顶层 name |
MCP Server 名,出现在 initialize 响应中 |
mcp.version |
string | 1.0.0 |
Server 版本 |
mcp.useStreamable |
bool | false |
是否使用 Streamable HTTP 传输 |
mcp.sseEndpoint |
string | /sse |
SSE 连接路径 |
mcp.messageEndpoint |
string | /message |
JSON-RPC 消息路径 |
mcp.sseTimeout |
duration | 24h |
SSE 连接允许的最大时长 |
mcp.messageTimeout |
duration | 30s |
请求执行允许的最大时长 |
mcp.cors |
[]string | — | 允许的跨域来源列表 |
两点值得注意的细节:
mcp.name为空时,服务器构造逻辑会自动回退到顶层name;mcp.version为空时回退到1.0.0(见 mcp/server.go);cors不为空时,底层会以rest.MustNewServer(c.RestConf, rest.WithCors(c.Mcp.Cors...))创建带 CORS 中间件的 REST Server;为空则直接使用rest.MustNewServer(c.RestConf)(见 mcp/server.go)。
快速开始:构建第一个 MCP Server
完整的最小可运行示例(与 mcp/readme.md 一致):
package main
import (
"context"
"log"
"github.com/zeromicro/go-zero/core/conf"
"github.com/zeromicro/go-zero/mcp"
)
type GreetArgs struct {
Name string `json:"name" jsonschema:"description=Name of the person to greet"`
}
func main() {
// 加载配置
var c mcp.McpConf
conf.MustLoad("config.yaml", &c)
// 创建 MCP server
server := mcp.NewMcpServer(c)
// 注册工具,SDK 会根据 struct tag 自动生成 JSON Schema
tool := &mcp.Tool{
Name: "greet",
Description: "Greet someone by name",
}
handler := func(ctx context.Context, req *mcp.CallToolRequest, args GreetArgs) (*mcp.CallToolResult, any, error) {
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{Text: "Hello, " + args.Name + "!"},
},
}, nil, nil
}
// 类型安全泛型注册,无需导入官方 SDK
mcp.AddTool(server, tool, handler)
// 启动服务
defer server.Stop()
server.Start()
}
启动后,服务会监听 host:port,SSE 模式下客户端可连接 http://localhost:8080/sse 完成 MCP 握手并调用 greet 工具。
生命周期与内部结构
McpServer 接口只暴露 Start() 与 Stop() 两个方法(mcp/server.go),其实现 mcpServerImpl 内部持有三样东西:
httpServer *rest.Server:go-zero 的 REST Server,负责 HTTP 层;mcpServer *sdkmcp.Server:官方 SDK 的 MCP Server 核心;options serverOptions:可选的服务器构造选项。
Start() 会打印 Starting MCP server <name> v<version> on host:port 日志并启动底层 REST Server;Stop() 则优雅关闭(mcp/server.go)。
添加 Tools:类型安全的泛型注册
工具是 MCP 客户端可调用的函数。go-zero 通过 mcp.AddTool<a href="https://link.gitcode.com/i/7a5510bbd4116c6e43f7bf3d3e699cbd" target="_blank">In, Out] 泛型包装([mcp/types.go),把官方 SDK 的类型安全能力直接暴露给业务层。SDK 会根据 Args 结构体上的 json 与 jsonschema 标签自动生成 JSON Schema,供客户端做参数校验与提示。
一个支持枚举约束与错误返回的示例:
type CalculateArgs struct {
Operation string `json:"operation" jsonschema:"enum=add,enum=subtract,enum=multiply,enum=divide"`
A float64 `json:"a" jsonschema:"description=First number"`
B float64 `json:"b" jsonschema:"description=Second number"`
}
tool := &mcp.Tool{
Name: "calculate",
Description: "Perform arithmetic operations",
}
handler := func(ctx context.Context, req *mcp.CallToolRequest, args CalculateArgs) (*mcp.CallToolResult, any, error) {
var result float64
switch args.Operation {
case "add":
result = args.A + args.B
case "subtract":
result = args.A - args.B
case "multiply":
result = args.A * args.B
case "divide":
if args.B == 0 {
return &mcp.CallToolResult{IsError: true}, nil, fmt.Errorf("division by zero")
}
result = args.A / args.B
}
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{Text: fmt.Sprintf("Result: %v", result)},
},
}, result, nil
}
mcp.AddTool(server, tool, handler)
关于泛型参数的说明(源自 mcp/types.go 与测试用例):
In是参数结构体,驱动 JSON Schema 生成;Out是结构化返回类型,handler 的第二个返回值会携带计算结果,可用于客户端拿到结构化数据(而非纯文本);- handler 签名固定为
func(ctx, *CallToolRequest, In) (*CallToolResult, Out, error)。
测试用例 mcp/server_test.go 展示了结构化输出(CalculateResult{Sum})的实际写法。另外注意,mcp.AddTool 内部会断言 server 是否为 *mcpServerImpl,若传入自定义实现会记录错误日志而非 panic(mcp/server_test.go)。
添加 Prompts:可复用的消息模板
Prompts 为客户端提供可复用的消息模板,比如"代码评审"类提示词:
prompt := &mcp.Prompt{
Name: "code-review",
Description: "Review code for best practices",
}
handler := func(ctx context.Context, req *sdkmcp.GetPromptRequest, args map[string]string) (*mcp.GetPromptResult, error) {
code := args["code"]
language := args["language"]
return &mcp.GetPromptResult{
Messages: []mcp.PromptMessage{
{
Role: "user",
Content: &mcp.TextContent{
Text: fmt.Sprintf("Please review this %s code:\n\n%s", language, code),
},
},
},
}, nil
}
server.AddPrompt(prompt, handler)
PromptHandler 的类型签名定义在 mcp/types.go。需要提醒的是:在向官方 SDK 迁移的过程中,server.AddPrompt() / server.AddResource() 这类便捷方法在 SDK v1.2.0 版本存在限制而被移除,相关注册应通过底层 SDK server 完成(见 mcp/MIGRATION.md 与 mcp/MIGRATION.md),使用时请以当前 go-sdk 版本(v1.4.1)的 API 为准。
添加 Resources:向模型提供可读数据
Resources 用于向模型暴露可读取的数据,例如项目文档:
resource := &mcp.Resource{
URI: "file:///docs/readme.md",
Name: "README",
Description: "Project documentation",
MimeType: "text/markdown",
}
handler := func(ctx context.Context, req *sdkmcp.ReadResourceRequest, uri string) (*mcp.ReadResourceResult, error) {
content, err := os.ReadFile("README.md")
if err != nil {
return nil, err
}
return &mcp.ReadResourceResult{
Contents: []mcp.ResourceContents{
{
URI: uri,
MimeType: "text/markdown",
Text: string(content),
},
},
}, nil
}
server.AddResource(resource, handler)
ResourceHandler 签名定义于 mcp/types.go,mcp.Resource、mcp.ResourceContents、mcp.ReadResourceResult 等类型均为官方 SDK 类型的再导出,方便业务代码统一使用 mcp. 前缀。
双传输支持:SSE 与 Streamable HTTP
go-zero 的 mcp 包根据 mcp.useStreamable 配置在两种传输之间切换,底层逻辑见 mcp/server.go。
SSE 传输(默认,2024-11-05 规范)
mcp:
useStreamable: false
sseEndpoint: /sse
这是 MCP 最初的 HTTP 传输方案:客户端通过 GET 建立 SSE 长连接接收服务端事件,通过 POST /message 发送 JSON-RPC 消息。
Streamable HTTP 传输(2025-03-26 规范)
mcp:
useStreamable: true
messageEndpoint: /message
新版规范提供更好的连接管理,GET 与 POST 都落在 messageEndpoint 上:GET 建立可复用的流式通道,POST 承载 JSON-RPC 请求。
路由注册的底层实现
无论哪种传输,registerRoutes 都会为同一个端点注册两条路由(mcp/server.go):
s.httpServer.AddRoute(rest.Route{
Method: http.MethodGet,
Path: endpoint,
Handler: handler.ServeHTTP,
}, rest.WithSSE(), rest.WithTimeout(s.conf.Mcp.SseTimeout))
s.httpServer.AddRoute(rest.Route{
Method: http.MethodPost,
Path: endpoint,
Handler: handler.ServeHTTP,
}, rest.WithTimeout(s.conf.Mcp.MessageTimeout))
即 GET 请求使用 rest.WithSSE()(正确设置 text/event-stream 响应头)并受 sseTimeout 约束;POST 请求受 messageTimeout 约束。测试 mcp/server_test.go 真实启动了 Streamable 模式服务,验证了 GET 与 POST 均能正常响应。
Request Metadata Bridge:多租户与请求上下文感知
对于多租户或需要感知请求上下文的工具,可以在传输边界一次性抽取选定的 HTTP 元数据,handler 中从 context.Context 读取。启用方式是通过 NewMcpServerWithOptions 注入提取器:
server := mcp.NewMcpServerWithOptions(c,
mcp.WithRequestMetadataExtractor(mcp.DefaultRequestMetadataExtractor),
)
handler := func(ctx context.Context, req *mcp.CallToolRequest, args SomeArgs) (*mcp.CallToolResult, any, error) {
tenant, _ := mcp.HeaderFromContext(ctx, "X-Tenant-Id")
traceID, _ := mcp.QueryFromContext(ctx, "trace")
scope, _ := mcp.PathFromContext(ctx, "scope")
_ = tenant
_ = traceID
_ = scope
return &mcp.CallToolResult{}, nil, nil
}
可用辅助函数
RequestMetadataFromContext(ctx):返回完整RequestMetadata{Headers, Query, Path};HeaderFromContext(ctx, key):取首个匹配的请求头值(键按http.CanonicalHeaderKey规范化);QueryFromContext(ctx, key):取首个匹配的查询参数值;PathFromContext(ctx, key):取路径变量值。
底层原理
该机制在 mcp/request_metadata.go 与 mcp/server.go 中实现:
DefaultRequestMetadataExtractor会克隆请求头、URL 查询参数以及pathvar.Vars(r)中的路径变量(依赖 go-zero 的 rest/pathvar 包);wrapRequestMetadata将抽取结果放入context.WithValue(r.Context(), requestMetadataCtxKey{}, metadata),再交给 MCP handler 链;- 所有数据都经过深拷贝(
cloneHeaderValues等),避免并发读写竞态。
端点的路径变量在 MCP 场景下同样可用——测试 mcp/server_test.go 将 sseEndpoint 配置为 /sse/:scope,真实启动服务后用官方 SDK 客户端发起工具调用,同时携带 X-Tenant-Id 请求头、tenant 查询参数与路径中的 scope=prod,在 handler 中逐一校验,最终断言调用成功且未标记错误。这从端到端验证了元数据桥接的完整链路。
从旧版迁移到官方 SDK
若你正从 go-zero 自研的旧版 MCP 实现迁移,可参考 mcp/MIGRATION.md 的要点:
- 依赖:
go get github.com/modelcontextprotocol/go-sdk@v1.2.0(当前仓库为 v1.4.1); - 类型系统:
Tool、CallToolRequest、CallToolResult、内容类型、Prompt、Resource、Server等全部改为官方 SDK 类型的再导出; - 注册方式:
server.AddTool(tool, handler)已移除,改为sdkmcp.AddTool(server.Server(), tool, handler)(go-zero 也提供了等价的mcp.AddTool泛型包装,见 mcp/types.go);SDK 注册不再返回 error; - 配置变更:移除
ProtocolVersion、BaseUrl字段,新增UseStreamable选择传输; - 收益:官方维护、编译期类型安全(Go 泛型)、自动 JSON Schema 生成、双传输支持。
小结与适用边界
go-zero 的 mcp 包把 Model Context Protocol 的能力以"配置 + 少量注册代码"的方式注入到了成熟的 REST Server 体系:协议细节由官方 SDK 负责,HTTP 生命周期、CORS、超时与日志则由 go-zero 框架接管。从 mcp/server_test.go 可以看到,SSE/Streamable 两种传输、配置默认值、泛型工具注册、结构化输出以及请求元数据桥接均已有自动化测试覆盖,可作为自建 MCP Server 的行为参考基准。
需要注意的是:本文描述的行为均以当前仓库的快照为准(go-sdk v1.4.1),MCP 规范仍在演进,涉及版本升级时请优先参考仓库内最新的 mcp/MIGRATION.md 与官方 SDK 文档确认 API 变化。