在 Kratos 中构建 MCP Server:基于 mcp-go 的 MCP 传输层实战指南

原创2026-09-19 17:02:051,959 阅读
文章标签:后端微服务RPC框架Web框架云原生

在 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)
    }
}

整个流程可以拆解为五个动作:

  1. 创建 MCP Server:tm.NewServer("kratos-mcp", "v1.0.0", ...) 传入服务名与版本号,这是 MCP 握手阶段(initialize)需要声明的 ServerInfo;
  2. 定义 Tool:使用 mcp.NewTool 声明工具的元信息,包括描述与参数 Schema(name 为必填字符串);
  3. 注册处理器:srv.AddTool(tool, helloHandler) 将工具与处理函数绑定,处理函数签名固定为 func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error);
  4. 装配 Kratos 应用:通过 kratos.Server(srv) 把 MCP Server 作为传输层注册进应用;
  5. 启动: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
}

关键链路一目了然:

  1. 先应用用户选项(地址、中间件、mcp-go 选项等);
  2. 用 mcp-go 创建 MCPServer(携带 ServerInfo 名称与版本);
  3. 创建底层 http.Server,其 Handler 是 srv.middleware(srv)——即用户的中间件包裹 Server 自身(因为 Server 实现了 http.Handler);
  4. 创建 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 的基本契约成立,可作为集成测试的参考模板。

使用注意事项与适用前提

  1. 传输方式:当前实现基于 mcp-go 的 SSE 传输端点(server.go),客户端需支持 SSE 模式连接;
  2. 版本前提:模块要求 Go 1.25.5+,且通过 replace 指令绑定仓库根目录的 Kratos v3 核心(见 go.mod);
  3. 工具 Schema 描述:建议为每个 Tool 提供清晰的 mcp.WithDescription 与参数描述,因为 MCP 客户端(LLM)正是依据这些元信息决定何时调用哪个工具,描述质量直接影响 AI 调用的准确率;
  4. 参数运行时校验:类型断言不可省略,这是处理器面对不可信调用时最重要的防线;
  5. 端点注册:如需自定义上报到注册中心的地址(例如部署在 NAT 或 Kubernetes 场景下),请使用 tm.Endpoint(...) 显式指定。

小结

contrib/transport/mcp 以极小的封装成本,把 mcp-go 的协议能力完整纳入 Kratos 的传输层体系:开发者只需关注「定义工具、实现处理器」,而服务生命周期、中间件、健康检查、端点注册等框架级能力由 Kratos 统一承担。它让「让 AI 调用你的 Go 服务」从拼凑多个库的繁琐工作,收敛为一次 NewServer + AddTool + kratos.Server 的标准流程。

登录后查看全文
kratos