gRPC MCP网关
grpc-mcp-gateway 是一个Go代码生成器，它使用protobuf注释将gRPC服务方法映射到MCP工具，其精神与 grpc-gateway 但针对MCP而不是REST。
什么是MCP？
MCP（模型上下文协议）是一种轻量级协议，允许AI客户端发现工具并通过简单的JSON-RPC接口调用它们。它提供了一种公开功能（工具）的标准方法，以便模型可以安全一致地与您的系统交互。
状态
- 从带注释的gRPC方法生成MCP工具注册。
- 桥接MCP工具对gRPC方法的调用。
- 支持MCP工具元数据（名称、标题、描述、注释）。
- 为从protobuf消息定义派生的工具输入生成强类型JSON模式。
- 提供轻量级的MCP HTTP处理程序(
runtime.MCPServeMux)具有可插拔的请求日志记录功能。 - 使MCP工具保持无状态（无会话）。
MCP规范兼容性
| grpc mcp网关版本 | mcp规范版本 |
|---|---|
| v0.6.0+ | 2025-11-25（JSON-RPC 2.0） |
MCP注释
在原型文件中定义MCP注释以及任何REST注释：
syntax = "proto3";
package demo.v1;
import "google/api/annotations.proto";
import "mcp/gateway/v1/annotations.proto";
service Greeter {
rpc SayHello(HelloRequest) returns (HelloReply) {
option (google.api.http) = {
post: "/v1/hello"
body: "*"
};
option (mcp.gateway.v1.mcp) = {
tool: {
name: "greeter.say_hello"
title: "Say Hello"
description: "Greets a caller."
read_only: true
}
};
}
}注释模式位于 proto/mcp/gateway/v1/annotations.proto.
发电机使用情况
protoc \
-I . \
-I ./proto \
--go_out=. --go-grpc_out=. \
--mcp-gateway_out=. \
path/to/your.protoBuf使用
如果您使用Buf生成protos，请安装该插件并将其添加到您的 buf.gen.yaml.
安装Buf：
brew install buf安装插件（put protoc-gen-mcp-gateway 在您的路径上）：
go install github.com/linkbreakers-com/grpc-mcp-gateway/cmd/protoc-gen-mcp-gateway@latest示例 buf.gen.yaml:
version: v1
plugins:
- name: go
out: generated/go
- name: go-grpc
out: generated/go
- name: mcp-gateway
out: generated/go然后运行：
buf generate生成API
对于每个带有注释方法的服务，生成器都会发出：
func RegisterMCPHandler(mux *runtime.MCPServeMux, client Client)这将为带注释的方法注册MCP工具，并将MCP工具调用路由到gRPC客户端。
最少的服务器启动
lis, _ := net.Listen("tcp", ":50051")
grpcServer := grpc.NewServer()
demov1.RegisterGreeterServer(grpcServer, greeterSvc)
go grpcServer.Serve(lis)
conn, _ := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
client := demov1.NewGreeterClient(conn)
handler := runtime.NewMCPServeMux(
runtime.ServerMetadata{Name: "greeter-mcp", Version: "v0.1.0"},
runtime.WithRequestLogger(func(ctx context.Context, req *runtime.MCPRequest) {
// Optional: log MCP requests here
}),
)
demov1.RegisterGreeterMCPHandler(handler, client)
http.ListenAndServe(":8090", handler)日志记录示例
使用 WithRequestLogger 记录每个MCP请求，并提供方法特定的详细信息：
logger := runtime.WithRequestLogger(func(ctx context.Context, req *runtime.MCPRequest) {
switch req.Method {
case "tools/call":
name, _ := req.Params["name"].(string)
if name == "" {
log.Printf("MCP tools/call")
return
}
log.Printf("MCP tools/call: %s", name)
case "tools/list":
log.Printf("MCP tools/list - client discovering tools")
case "initialize":
log.Printf("MCP initialize - client connecting")
case "notifications/initialized":
log.Printf("MCP notifications/initialized - handshake complete")
default:
log.Printf("MCP %s", req.Method)
}
})
mux := runtime.NewMCPServeMux(
runtime.ServerMetadata{Name: "greeter-mcp", Version: "v0.1.0"},
logger,
)日志输出示例：
2026/02/11 09:41:02 MCP initialize - client connecting
2026/02/11 09:41:02 MCP notifications/initialized - handshake complete
2026/02/11 09:41:03 MCP tools/list - client discovering tools
2026/02/11 09:41:04 MCP tools/call: greeter.say_hello最小客户端请求（curl）
列出工具：
curl -s http://localhost:8090/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'调用工具：
curl -s http://localhost:8090/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"greeter.say_hello","arguments":{"name":"Ada"}}}'生产说明
- 在MCP处理程序之前的HTTP层添加身份验证和令牌验证。
- 如果MCP客户端在浏览器或远程环境中运行，请配置CORS。
- 在HTTP服务器和gRPC客户端上设置超时，以避免挂起工具调用。
- 通过传递使用结构化日志记录
WithRequestLogger在您的MCP多路复用器中。
完整生产示例
有关显示所有最佳实践的全面、生产就绪的实施，请参阅：
此示例演示了：
- JSON-RPC错误处理的承载令牌身份验证
- 请求记录所有MCP协议消息
- Kubernetes的健康检查端点
- CORS配置
- 正确处理
notifications/initialized - 身份验证失败调试的响应记录
- gRPC↔ HTTP双服务器架构
- Kubernetes部署模式
非常适合构建生产MCP服务器的团队。
客户端示例（端到端）
此回购包括一个调用 echo HTTP工具：
# In one terminal, start the echo server:
go run ./examples/structecho
# In another terminal, call the tool:
go run ./examples/structecho-client真实protobuf+gRPC示例
完整的端到端测试（gRPC服务器+MCP网关+MCP客户端）存在于：
github.com/linkbreakers-com/grpc-mcp-gateway/examples/greeter
运行测试：
go test ./examples/greeter -run TestGreeterMCPFlow生产中
该库在Linkbreakers的生产环境中使用。我们开源，使任何拥有Protobuf/gRPC API的团队都能轻松快速添加MCP支持，因为我们相信MCP将成为将工具集成到人工智能工作流程中的一种越来越重要的方式。
Linkbreakers MCP服务器：https://mcp.linkbreakers.com\ MCP目录列表：https://mcp.so/server/linkbreakers
模式生成
生成器为每个工具生成强类型的JSON模式 inputSchema，直接来源于protobuf消息定义。这是受到以下方式的启发 grpc-gateways protoc-gen-openapiv2 生成OpenAPI模式。
生成的内容：
- 字段类型：原型标量类型映射到JSON模式类型(
string,integer,number,boolean)与适当format价值观(int32,int64,float,double,byte,date-time). - 枚举字段：所有枚举值都列在
enum阵列。零值哨兵（例如。TYPE_UNSPECIFIED)被排除在外，因此MCP客户端始终选择一个有效值。 - 嵌套消息：递归扩展为对象模式
properties. - 重复字段：映射到
{"type": "array", "items": ...}. - 映射字段：映射到
{"type": "object", "additionalProperties": ...}. - 知名类型:
google.protobuf.Timestamp→date-time字符串，Struct→ 开放对象、包装器类型→ 其潜在类型等。 google.api.field_behavior:OUTPUT_ONLY字段被排除在输入模式之外。REQUIRED字段将添加到required阵列。- 描述：从原型注释中提取并包含在模式中。
示例——给定此原型消息：
message CreateTaskRequest {
// The title of the task
string title = 1 [(google.api.field_behavior) = REQUIRED];
// The priority level
Task.Priority priority = 2;
// Tags to associate with the task
repeated string tags = 3;
}
message Task {
enum Priority {
PRIORITY_UNSPECIFIED = 0;
PRIORITY_LOW = 1;
PRIORITY_HIGH = 2;
}
}发电机产生：
InputSchema: map[string]any{
"additionalProperties": false,
"properties": map[string]any{
"title": map[string]any{
"description": "The title of the task",
"type": "string",
},
"priority": map[string]any{
"description": "The priority level",
"enum": []string{"PRIORITY_LOW", "PRIORITY_HIGH"},
"type": "string",
},
"tags": map[string]any{
"description": "Tags to associate with the task",
"items": map[string]any{"type": "string"},
"type": "array",
},
},
"required": []string{"title"},
"type": "object",
},局限性
- 仅支持一元RPC（跳过流式RPC）。
项目布局
cmd/protoc-gen-mcp-gateway：协议插件（代码生成器+模式构建器）proto/mcp/gateway/v1/annotations.proto：MCP注释定义runtime：MCP\protobuf转换帮助程序