在 Kratos 中构建 MCP Server:基于 mcp-go 的 MCP 传输层实战指南
在 Kratos 中构建 MCP Server:基于 mcp-go 的 MCP 传输层实战指南
导读
本文围绕 Kratos 官方 contrib 模块 contrib/transport/mcp 展开,讲解如何在 Go 微服务框架 Kratos 中一键接入 MCP(Model Context Protocol)服务端能力:从快速启动一个 MCP Server、注册 Tool 及其处理器,到与 kratos.New 应用无缝集成,再到中间件、SSE、端点注册等进阶选项的源码级剖析。读完本文,你将能够基于 Kratos 在几分钟内暴露一个可供 Claude、Cursor 等 MCP 客户端调用的工具服务,并理解其底层实现原理与生命周期契约。
MCP 与 Kratos 的切入点
MCP(Model Context Protocol)是当前 AI 应用生态中连接大模型与外部工具的事实标准协议。Kratos 作为云原生时代的 Go 微服务框架,在 contrib/transport 目录下提供了对 MCP 的内置支持:contrib/transport/mcp 模块在 Kratos 之上封装了开源库 mark3labs/mcp-go 的服务端能力,使其以 Kratos 标准传输层(transport.Server)的形式存在,从而可以像注册 HTTP/gRPC 服务一样,把 MCP 服务挂载进 Kratos 应用。
从模块的 go.mod 可以看出其依赖关系:
module github.com/go-kratos/kratos/contrib/transport/mcp/v3
go 1.25.5
require (
github.com/go-kratos/kratos/v3 v3.0.0
github.com/mark3labs/mcp-go v0.54.0
)
// 本地开发时通过 replace 指向仓库根目录
replace github.com/go-kratos/kratos/v3 => ../../../
该模块直接依赖 Kratos v3 核心与 mcp-go v0.54.0,职责边界非常清晰:协议细节交给 mcp-go,生命周期与框架集成交给 Kratos。
快速开始:5 步启动一个 MCP Server
以下示例来自 README 的 Quick start,我们先完整还原,再逐步拆解。
import (
tm "github.com/go-kratos/kratos/contrib/transport/mcp/v3"
mcp "github.com/mark3labs/mcp-go/mcp"
)
func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
name, ok := request.Params.Arguments["name"].(string)
if !ok {
return nil, errors.New("name must be a string")
}
return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil
}
func Health(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/health/ready" {
w.WriteHeader(http.StatusOK)
return
}
next.ServeHTTP(w, r)
})
}
func main() {
srv := tm.NewServer("kratos-mcp", "v1.0.0", tm.Address(":8000"), tm.Middleware(Health))
tool := mcp.NewTool("hello_world",
mcp.WithDescription("Say hello to someone"),
mcp.WithString("name",
mcp.Required(),
mcp.Description("Name of the person to greet"),
),
)
// Add tool handler
srv.AddTool(tool, helloHandler)
// creates a kratos application
app := kratos.New(
kratos.Name("kratos-app"),
kratos.Server(srv),
)
if err := app.Run(); err != nil {
panic(err)
}
}
整个流程可以拆解为五个动作:
- 创建 MCP Server:
tm.NewServer("kratos-mcp", "v1.0.0", ...)传入服务名与版本号,这是 MCP 握手阶段(initialize)需要声明的 ServerInfo; - 定义 Tool:使用
mcp.NewTool声明工具的元信息,包括描述与参数 Schema(name为必填字符串); - 注册处理器:
srv.AddTool(tool, helloHandler)将工具与处理函数绑定,处理函数签名固定为func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error); - 装配 Kratos 应用:通过
kratos.Server(srv)把 MCP Server 作为传输层注册进应用; - 启动:
app.Run()统一拉起所有注册的 Server。
处理器与工具参数解析
helloHandler 演示了 MCP 工具处理器的典型写法:从 request.Params.Arguments 中按参数名取出值,进行类型断言与校验,最后用 mcp.NewToolResultText 构造文本类型的结果。注意两点:
- 参数校验是必须的:即使工具 Schema 中声明了
mcp.Required(),运行时仍可能收到类型不符的调用(例如name不是字符串),因此处理器内必须做类型断言; - 错误处理:返回
error会让 MCP 客户端收到调用失败响应,errors.New("name must be a string")这类描述性错误信息会原样透传给调用方,便于调试。
健康检查中间件
示例中的 Health 是一个标准 Go http.Handler 中间件:当请求路径为 /health/ready 时直接返回 200,其余请求放行给下一个 Handler。这展示了 MCP 模块的一个特色能力——可以在 MCP 服务上叠加自定义 HTTP 中间件,让 MCP 端点同时具备健康检查等运维能力。
源码剖析:Server 的设计与选项
深入 server.go 可以看到,Server 结构体本质上是 mcp-go 的 MCPServer 与标准 http.Server 的组合体,并同时实现了 Kratos 的多个接口:
var (
_ transport.Server = (*Server)(nil)
_ transport.Endpointer = (*Server)(nil)
_ http.Handler = (*Server)(nil)
)
Server 的核心字段包括:
type Server struct {
*server.MCPServer // 内嵌 mcp-go 的 MCPServer,提供 AddTool 等协议能力
srv *http.Server // 底层 HTTP 服务器
sse *server.SSEServer // 基于 SSE 的 MCP 传输端点
middleware MiddlewareFunc // 用户自定义 HTTP 中间件
address string // 监听地址
endpoint *url.URL // 注册中心端点
srvOpts []server.ServerOption
sseOpts []server.SSEOption
}
选项(ServerOption)总览
NewServer 通过函数式选项模式装配配置,支持的选项如下:
| 选项 | 函数签名 | 作用 |
|---|---|---|
Address |
Address(addr string) ServerOption |
设置 HTTP 监听地址,默认 :8000 |
Endpoint |
Endpoint(endpoint *url.URL) ServerOption |
显式指定注册到服务发现的端点地址 |
Middleware |
Middleware(m MiddlewareFunc) ServerOption |
设置 HTTP 中间件,默认透传(func(next http.Handler) http.Handler { return next }) |
SrvOptions |
SrvOptions(opts ...server.ServerOption) ServerOption |
透传 mcp-go 的 MCPServer 选项(如鉴权、能力声明等) |
SSEOptions |
SSEOptions(opts ...server.SSEOption) ServerOption |
透传 mcp-go SSE 服务器的选项 |
NewServer 的装配逻辑
func NewServer(name, version string, opts ...ServerOption) *Server {
srv := &Server{
address: ":8000",
middleware: func(next http.Handler) http.Handler { return next },
}
for _, o := range opts {
o(srv)
}
srv.MCPServer = server.NewMCPServer(name, version, srv.srvOpts...)
srv.srv = &http.Server{Addr: srv.address, Handler: srv.middleware(srv)}
srv.sse = server.NewSSEServer(srv.MCPServer, append(srv.sseOpts, server.WithHTTPServer(srv.srv))...)
return srv
}
关键链路一目了然:
- 先应用用户选项(地址、中间件、mcp-go 选项等);
- 用 mcp-go 创建
MCPServer(携带 ServerInfo 名称与版本); - 创建底层
http.Server,其 Handler 是srv.middleware(srv)——即用户的中间件包裹Server自身(因为Server实现了http.Handler); - 创建
SSEServer,把MCPServer暴露为基于 SSE 的 MCP 传输端点。
也就是说,MCP 的服务端传输在当前实现中走的是 SSE 通道,而 Server.ServeHTTP 直接委托给 s.sse.ServeHTTP:
func (s *Server) ServeHTTP(res http.ResponseWriter, req *http.Request) {
s.sse.ServeHTTP(res, req)
}
生命周期与 Kratos 接口契约
要让 MCP 服务作为 Kratos 传输层工作,Server 必须实现 transport.Server 接口。对照源码:
// transport.Server 要求:
type Server interface {
Start(context.Context) error
Stop(context.Context) error
}
MCP 模块的实现为:
// Start start the MCP server.
func (s *Server) Start(_ context.Context) error {
if err := s.srv.ListenAndServe(); err != nil {
if !errors.Is(err, http.ErrServerClosed) {
return err
}
}
return nil
}
// Stop stop the MCP server.
func (s *Server) Stop(ctx context.Context) error {
return s.sse.Shutdown(ctx)
}
Start启动底层 HTTP 服务,并在收到http.ErrServerClosed(正常关闭信号)时静默返回,避免把优雅关闭误判为错误;Stop调用sse.Shutdown(ctx)完成优雅停机。
同时 Server 还实现了 Endpointer 接口,用于向服务注册中心上报真实端点:
// Endpoint return a real address to registry endpoint.
// examples:
// - http://127.0.0.1:8000
func (s *Server) Endpoint() (*url.URL, error) {
if s.endpoint != nil {
return s.endpoint, nil
}
return url.Parse(fmt.Sprintf("http://%s", s.address))
}
若未通过 Endpoint 选项显式指定,则默认由监听地址推导为 http://<address> 格式(如 http://127.0.0.1:8000)。这意味着配合 kratos.Registrar(...) 使用时,MCP 服务也能自动完成服务注册。
在 Kratos 应用中装配与运行
Kratos 通过 options.go 的 kratos.Server 选项接受任意实现 transport.Server 的传输层:
// Server with transport servers.
func Server(srv ...transport.Server) Option {
return func(o *options) { o.servers = srv }
}
因此 MCP Server 可以与其他 Kratos 传输层(gRPC、HTTP)共存于同一个应用。当你调用 app.Run() 时,Kratos 会统一执行所有已注册 Server 的 Start,并在收到退出信号时统一执行 Stop——MCP 服务的启动、优雅关闭、服务注册全部交由框架托管,开发者无需关心底层 HTTP 服务器的细节。
实用示例:多传输层共存
app := kratos.New(
kratos.Name("kratos-app"),
kratos.Server(srv), // MCP Server(:8000,SSE 端点)
kratos.Server(grpcSrv), // gRPC Server(:9000)
kratos.Server(httpSrv), // HTTP Server(:8001)
)
测试验证
仓库为该模块提供了基础生命周期测试 server_test.go:
func TestServer(t *testing.T) {
var (
ctx = context.Background()
srv = NewServer("test", "v1.0.0", Address(":0"))
)
go func() {
if err := srv.Start(ctx); err != nil {
panic(err)
}
}()
time.Sleep(time.Second)
if err := srv.Stop(ctx); err != nil {
t.Fatal(err)
}
}
测试覆盖了「创建 → 启动 → 停止」的完整生命周期,其中 Address(":0") 让系统自动分配空闲端口,避免测试端口冲突。该用例验证了 Server 作为 transport.Server 的基本契约成立,可作为集成测试的参考模板。
使用注意事项与适用前提
- 传输方式:当前实现基于 mcp-go 的 SSE 传输端点(server.go),客户端需支持 SSE 模式连接;
- 版本前提:模块要求 Go 1.25.5+,且通过 replace 指令绑定仓库根目录的 Kratos v3 核心(见 go.mod);
- 工具 Schema 描述:建议为每个 Tool 提供清晰的
mcp.WithDescription与参数描述,因为 MCP 客户端(LLM)正是依据这些元信息决定何时调用哪个工具,描述质量直接影响 AI 调用的准确率; - 参数运行时校验:类型断言不可省略,这是处理器面对不可信调用时最重要的防线;
- 端点注册:如需自定义上报到注册中心的地址(例如部署在 NAT 或 Kubernetes 场景下),请使用
tm.Endpoint(...)显式指定。
小结
contrib/transport/mcp 以极小的封装成本,把 mcp-go 的协议能力完整纳入 Kratos 的传输层体系:开发者只需关注「定义工具、实现处理器」,而服务生命周期、中间件、健康检查、端点注册等框架级能力由 Kratos 统一承担。它让「让 AI 调用你的 Go 服务」从拼凑多个库的繁琐工作,收敛为一次 NewServer + AddTool + kratos.Server 的标准流程。