Skip to content
Back to search

protoc-gen-go-mcp

Go protobuf compiler extension to turn any gRPC service into an MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/redpanda-data--protoc-gen-go-mcp/badge.svg)](/listings/redpanda-data--protoc-gen-go-mcp)

HTML

<a href="/listings/redpanda-data--protoc-gen-go-mcp"><img src="/api/listings/redpanda-data--protoc-gen-go-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 363 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # `protoc-gen-go-mcp`
  2. [![Test](https://github.com/redpanda-data/protoc-gen-go-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/redpanda-data/protoc-gen-go-mcp/actions/workflows/test.yml)
  3. [![Go Report Card](https://goreportcard.com/badge/github.com/redpanda-data/protoc-gen-go-mcp)](https://goreportcard.com/report/github.com/redpanda-data/protoc-gen-go-mcp)
  4. [![codecov](https://codecov.io/gh/redpanda-data/protoc-gen-go-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/redpanda-data/protoc-gen-go-mcp)
  5. **`protoc-gen-go-mcp`** is a [Protocol Buffers](https://protobuf.dev) compiler plugin that generates [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers for your `gRPC` or `ConnectRPC` APIs.
  6. It generates `*.pb.mcp.go` files for each protobuf service, enabling you to delegate handlers directly to gRPC servers or clients. Under the hood, MCP uses JSON Schema for tool inputs -- `protoc-gen-go-mcp` auto-generates these schemas from your method input descriptors.
  7. Generated code is **MCP-library-agnostic**: pick [modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk) (the official SDK) or [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) at server creation time through a thin adapter -- no regeneration needed.
  8. ## Features
  9. - Auto-generates MCP handlers from your `.proto` services
  10. - Outputs JSON Schema for method inputs
  11. - Wire up to gRPC or ConnectRPC servers/clients
  12. - Easy integration with [`buf`](https://buf.build)
  13. - Runtime LLM provider selection -- standard MCP or OpenAI-compatible schemas
  14. - MCP library agnostic -- official go-sdk and mark3labs/mcp-go both supported
  15. ## Usage
  16. ### Generate code
  17. Add entry to your `buf.gen.yaml`:
  18. ```
  19. ...
  20. plugins:
  21. - local:
  22. - go
  23. - run
  24. - github.com/redpanda-data/protoc-gen-go-mcp/cmd/protoc-gen-go-mcp@latest
  25. out: ./gen/go
  26. opt: paths=source_relative
  27. ```
  28. You need to generate the standard `*.pb.go` files as well. `protoc-gen-go-mcp` by defaults uses a separate subfolder `{$servicename}mcp`, and imports the `*pb.go` files -- similar to connectrpc-go.
  29. After running `buf generate`, you will see a new folder for each package with protobuf Service definitions:
  30. ```
  31. tree pkg/testdata/gen/
  32. gen
  33. go
  34. testdata
  35. test_service.pb.go
  36. testdataconnect/
  37. test_service.connect.go
  38. testdatamcp/
  39. test_service.pb.mcp.go
  40. ```
  41. ### Setting up the MCP server
  42. Generated code programs against the `runtime.MCPServer` interface. You choose the backing MCP library by importing the corresponding adapter package.
  43. #### With the official go-sdk (recommended)
  44. ```go
  45. import (
  46. "github.com/modelcontextprotocol/go-sdk/mcp"
  47. "github.com/redpanda-data/protoc-gen-go-mcp/pkg/runtime/gosdk"
  48. )
  49. // Create server -- raw is *mcp.Server for transport, s is runtime.MCPServer for tools.
  50. raw, s := gosdk.NewServer("my-server", "1.0.0")
  51. testdatamcp.RegisterTestServiceHandler(s, &srv)
  52. // Serve over stdio
  53. raw.Run(ctx, &mcp.StdioTransport{})
  54. ```
  55. #### With mark3labs/mcp-go
  56. ```go
  57. import (
  58. "github.com/mark3labs/mcp-go/server"
  59. "github.com/redpanda-data/protoc-gen-go-mcp/pkg/runtime/mark3labs"
  60. )
  61. // Create server -- raw is *server.MCPServer for transport, s is runtime.MCPServer for tools.
  62. raw, s := mark3labs.NewServer("my-server", "1.0.0")
  63. testdatamcp.RegisterTestServiceHandler(s, &srv)
  64. // Serve over stdio
  65. server.ServeStdio(raw)
  66. ```
  67. ### Wiring up handlers
  68. Example for in-process registration:
  69. ```go
  70. srv := testServer{} // your gRPC implementation
  71. // Register all RPC methods as tools on the MCP server
  72. testdatamcp.RegisterTestServiceHandler(s, &srv)
  73. ```
  74. Each RPC method in your protobuf service becomes an MCP tool.
  75. ### Runtime LLM Provider Selection
  76. You can choose LLM compatibility at runtime without regenerating code:
  77. ```go
  78. // Option 1: Use convenience function with runtime provider selection
  79. testdatamcp.RegisterTestServiceHandlerWithProvider(s, &srv, runtime.LLMProviderOpenAI)
  80. // Option 2: Register specific handlers directly
  81. testdatamcp.RegisterTestServiceHandler(s, &srv) // Standard MCP
  82. testdatamcp.RegisterTestServiceHandlerOpenAI(s, &srv) // OpenAI-compatible
  83. ```
  84. ### Wiring up with grpc and connectrpc client
  85. Forward MCP tool calls directly to gRPC clients:
  86. ```go
  87. testdatamcp.ForwardToTestServiceClient(s, myGrpcClient)
  88. ```
  89. Same for connectrpc:
  90. ```go
  91. testdatamcp.ForwardToConnectTestServiceClient(s, myConnectClient)
  92. ```
  93. This directly connects the MCP handler to the client, requiring zero boilerplate.
  94. ### Extra properties
  95. It's possible to add extra properties to MCP tools, that are not in the proto. These are written into context.
  96. ```go
  97. // Enable URL override with custom field name and description
  98. option := runtime.WithExtraProperties(
  99. runtime.ExtraProperty{
  100. Name: "base_url",
  101. Description: "Base URL for the API",
  102. Required: true,
  103. ContextKey: MyURLOverrideKey{},
  104. },
  105. )
  106. // Use with any generated function
  107. testdatamcp.RegisterTestServiceHandler(s, &srv, option)
  108. testdatamcp.ForwardToTestServiceClient(s, client, option)
  109. ```
  110. ### Tool name prefixing
  111. When registering the same service multiple times (e.g. separate database instances), use `WithNamePrefix` to namespace tools:
  112. ```go
  113. sqlv1mcp.RegisterSQLServiceHandler(s, postgresHandler, runtime.WithNamePrefix("postgres"))
  114. sqlv1mcp.RegisterSQLServiceHandler(s, clickhouseHandler, runtime.WithNamePrefix("clickhouse"))
  115. // Tools: postgres_SQLService_Query, clickhouse_SQLService_Query, ...
  116. ```
  117. ### Tool naming
  118. By default a tool is named after the method's full proto name with dots replaced by underscores (`redpanda_mcps_sql_v1_SQLService_Query`). Names longer than 64 characters — the strictest provider limit — are truncated: a 10-character hash of the full name plus as much of the tail (the most specific part) as fits. The hash is forced to start with a letter because Gemini rejects function names that start with a digit.
  119. To publish a method under a stable, human-chosen name instead, set the `(mcp.v1.tool_name)` method option:
  120. ```proto
  121. import "mcp/v1/annotations.proto";
  122. rpc GetEquityResearchReport(GetEquityResearchReportRequest) returns (GetEquityResearchReportResponse) {
  123. option (mcp.v1.tool_name) = "get_equity_research_report";
  124. }
  125. ```
  126. The value must match `^[a-z_][a-z0-9_-]{0,63}$` — lowercase snake/kebab case within every provider's function-name rules; lowercase guarantees configured names pass untouched through consumers' de-mangling heuristics (they key on the UpperCamel `Service_` segment of derived names). Code generation fails on an invalid value and on duplicate tool names within a service (one service is one MCP server registration — different services may legitimately reuse a name). The dynamic registration path (`gen.RegisterService`) applies the same option; an invalid or colliding configured name there falls back to the derived name so a tool is never silently dropped.
  127. ## Migrating from mark3labs-only (pre-v0.2)
  128. Generated code no longer imports `mark3labs/mcp-go` directly. It programs against the `runtime.MCPServer` interface, and you pick the MCP library via an adapter package.
  129. ### 1. Server creation
  130. ```go
  131. // Before
  132. s := server.NewMCPServer("name", "1.0", server.WithToolCapabilities(true))
  133. // After -- mark3labs
  134. raw, s := mark3labs.NewServer("name", "1.0", server.WithToolCapabilities(true))
  135. // raw is *server.MCPServer for transport (ServeStdio, NewStreamableHTTPServer, etc.)
  136. // s is runtime.MCPServer for tool registration
  137. // After -- official go-sdk
  138. raw, s := gosdk.NewServer("name", "1.0")
  139. ```
  140. ### 2. Tool registration
  141. Generated `Register*Handler` functions now take `runtime.MCPServer` instead of `*server.MCPServer`. Just pass `s` from step 1.
  142. If you were calling `s.AddTool()` manually with mark3labs types to do name prefixing, delete that code and use `WithNamePrefix`:
  143. ```go
  144. // Before: 60 lines of manual register.go per service
  145. sql.RegisterTools(s, "postgres", handler) // custom wrapper around s.AddTool(mcp.Tool, ...)
  146. // After: one line
  147. sqlv1mcp.RegisterSQLServiceHandler(s, handler, runtime.WithNamePrefix("postgres"))
  148. ```
  149. ### 3. HandleError return type
  150. `runtime.HandleError()` now returns `*runtime.CallToolResult` instead of `*mcp.CallToolResult`. If you call it from custom handlers, update the return type.
  151. ### 4. Transport
  152. Transport setup is unchanged -- use the raw server from step 1:
  153. ```go
  154. // mark3labs stdio
  155. server.ServeStdio(raw)
  156. // mark3labs streamable HTTP
  157. mcpserver.NewStreamableHTTPServer(raw)
  158. // go-sdk stdio
  159. raw.Run(ctx, &mcp.StdioTransport{})
  160. ```
  161. ## LLM Provider Compatibility
  162. The generator creates both standard MCP and OpenAI-compatible handlers automatically. Choose which to use at runtime.
  163. ### Standard MCP
  164. - Full JSON Schema support (additionalProperties, anyOf, oneOf)
  165. - Maps represented as JSON objects
  166. - Well-known types use native JSON representations
  167. ### OpenAI Compatible
  168. - Restricted JSON Schema (no additionalProperties, anyOf, oneOf)
  169. - Maps converted to arrays of key-value pairs
  170. - Well-known types (Struct, Value, ListValue) encoded as JSON strings
  171. - All fields marked as required with nullable unions
  172. ## Development & Testing
  173. ### Commands
  174. All commands use [just](https://github.com/casey/just):
  175. ```bash
  176. just build # Build everything (Bazel)
  177. just test-unit # Unit + golden tests (no API keys needed)
  178. just test # All tests including conformance/integration (needs API keys)
  179. just test-cover # Tests with coverage report
  180. just generate # Regenerate proto code + descriptor set
  181. just lint # Run golangci-lint
  182. just fmt # Format code
  183. just install # Install binary to GOPATH/bin
  184. just gazelle # Sync BUILD files from go.mod
  185. # View all available commands
  186. just --list
  187. ```
  188. ### Development Workflow
  189. ```bash
  190. # 1. Edit proto or generator code
  191. # 2. Regenerate
  192. just generate
  193. # 3. Run tests
  194. just test-unit
  195. ```
  196. ### Golden File Testing
  197. The generator uses golden file testing to ensure output consistency. Tests re-run the generator in-process from compiled descriptors and compare against checked-in `*.pb.mcp.go` files.
  198. **To add new tests:** Drop a `.proto` file in `pkg/testdata/proto/testdata/` and run `just generate`. The golden test automatically discovers all generated files and compares them.
  199. ## Proto-to-JSON Schema mapping
  200. The plugin maps protobuf types to JSON Schema. Understanding these mappings matters because LLMs see the schema, not your proto definitions.
  201. ### Scalar types
  202. | Proto type | JSON Schema type | Notes |
  203. |---|---|---|
  204. | `double`, `float` | `number` | |
  205. | `int32`, `uint32`, `sint32`, `fixed32`, `sfixed32` | `integer` | |
  206. | `int64`, `uint64`, `sint64`, `fixed64`, `sfixed64` | `string` | JSON cannot represent 64-bit integers precisely |
  207. | `bool` | `boolean` | |
  208. | `string` | `string` | |
  209. | `bytes` | `string` | `contentEncoding: base64` |
  210. | `enum` | `string` | `enum` array with all value names |
  211. ### Messages and maps
  212. Nested messages become nested `object` schemas. Maps depend on the mode:
  213. **Standard mode:** `map<K, V>` becomes a JSON object with `propertyNames` constraints (e.g., `pattern` for int keys, `enum` for bool keys).
  214. **OpenAI mode:** `map<K, V>` becomes an array of `{key, value}` objects. Key constraints (patterns, enums) are preserved on the `key` field. At runtime, `FixOpenAI` converts these arrays back to objects before proto unmarshaling.
  215. ### Well-known types
  216. | Proto type | Standard schema | OpenAI schema |
  217. |---|---|---|
  218. | `google.protobuf.Timestamp` | `string` with `format: date-time` | Same |
  219. | `google.protobuf.Duration` | `string` with duration pattern | Same |
  220. | `google.protobuf.Struct` | `object` with `additionalProperties: true` | `string` (JSON-encoded) |
  221. | `google.protobuf.Value` | any (no type constraint) | `string` (JSON-encoded) |
  222. | `google.protobuf.ListValue` | `array` | `string` (JSON-encoded) |
  223. | `google.protobuf.FieldMask` | `string` | Same |
  224. | `google.protobuf.Any` | `object` with `@type` + `value` | Same, with `additionalProperties: false` |
  225. | Wrapper types (`StringValue`, etc.) | nullable scalar (e.g., `["string", "null"]`) | Same |
  226. In OpenAI mode, `FixOpenAI` handles the reverse transformation at runtime: JSON-encoded strings are parsed back, wrapper objects `{"value": X}` are unwrapped to `X`, and map arrays are converted to objects.
  227. ### Oneof fields
  228. **Standard mode:** Uses JSON Schema `anyOf` with one entry per oneof group. Each entry specifies one allowed alternative.
  229. **OpenAI mode:** Oneof fields are flattened into nullable fields (e.g., `type: ["string", "null"]`) with a description noting the oneof constraint. At runtime, `FixOpenAI` strips null oneof alternatives and keeps only the first non-null field per group.
  230. ### Validation constraints
  231. [buf.validate](https://buf.build/bufbuild/protovalidate) annotations are mapped to JSON Schema keywords:
  232. | Validation | JSON Schema |
  233. |---|---|
  234. | `string.uuid` | `format: uuid` |
  235. | `string.email` | `format: email` |
  236. | `string.pattern` | `pattern` |
  237. | `string.min_len/max_len` | `minLength/maxLength` |
  238. | `int32.gte/lte` | `minimum/maximum` |
  239. | `int32.gt/lt` | `minimum+1 / maximum-1` |
  240. | `float.gt/lt` | `exclusiveMinimum/exclusiveMaximum` |
  241. | `double.gte/lte` | `minimum/maximum` |
  242. ### Recursive messages
  243. Self-referencing and mutually recursive messages (e.g., tree nodes, linked lists) are supported. The schema expands up to 3 levels deep with full field detail. Beyond that, recursive fields become `{"type": "string", "description": "JSON-encoded TreeNode. Provide a JSON object as a string."}` -- the same pattern used for `Struct`/`Value`/`ListValue` in OpenAI mode.
  244. At runtime, `FixOpenAI` parses these string-encoded fields back into JSON objects before proto unmarshaling. The actual data can nest arbitrarily deep -- the depth limit only applies to the schema the LLM sees, not to what it can send.
  245. ### Tool name mangling
  246. If the fully qualified RPC name (dots replaced with underscores) exceeds 64 characters, the name is truncated: the head is replaced with a 10-character SHA-256 hash prefix, preserving the tail (the most specific part, typically `ServiceName_MethodName`). The 64-char limit exists because Claude desktop enforces it.
  247. ## Limitations
  248. - No interceptor support (yet). Registering with a gRPC server bypasses interceptors.
  249. - Recursive message schemas lose field-level detail beyond 3 levels of nesting (see above). The LLM must encode deeper levels as JSON strings.
  250. - Extra properties added via `WithExtraProperties` must not collide with proto field names. If they do, the extra property value will be extracted into context but will also leak into the proto message.
  251. ## Feedback
  252. We'd love feedback, bug reports, or PRs! Join the discussion and help shape the future of Go and Protobuf MCP tooling.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.