Generated code is MCP-library-agnostic: pick modelcontextprotocol/go-sdk (the official SDK) or mark3labs/mcp-go at server creation time through a thin adapter -- no regeneration needed.

Features

- Auto-generates MCP handlers from your .proto services
- Outputs JSON Schema for method inputs
- Wire up to gRPC or ConnectRPC servers/clients
- Easy integration with buf
- Runtime LLM provider selection -- standard MCP or OpenAI-compatible schemas
- MCP library agnostic -- official go-sdk and mark3labs/mcp-go both supported

Usage

Generate code

Add entry to your buf.gen.yaml:

...

plugins:

  - local:

      - go

      - run

      - github.com/redpanda-data/protoc-gen-go-mcp/cmd/protoc-gen-go-mcp@latest

    out: ./gen/go

    opt: paths=source_relative

After running buf generate, you will see a new folder for each package with protobuf Service definitions:

tree pkg/testdata/gen/
gen
  go
    testdata
      test_service.pb.go
      testdataconnect/
        test_service.connect.go
      testdatamcp/
        test_service.pb.mcp.go

Setting up the MCP server

Generated code programs against the runtime.MCPServer interface. You choose the backing MCP library by importing the corresponding adapter package.

With the official go-sdk (recommended)

Wiring up handlers

Example for in-process registration:

srv := testServer{} // your gRPC implementation
// Register all RPC methods as tools on the MCP server

testdatamcp.RegisterTestServiceHandler(s, &srv)

Each RPC method in your protobuf service becomes an MCP tool.

Runtime LLM Provider Selection

You can choose LLM compatibility at runtime without regenerating code:

// Option 1: Use convenience function with runtime provider selection
testdatamcp.RegisterTestServiceHandlerWithProvider(s, &srv, runtime.LLMProviderOpenAI)
// Option 2: Register specific handlers directly

testdatamcp.RegisterTestServiceHandler(s, &srv)        // Standard MCP

testdatamcp.RegisterTestServiceHandlerOpenAI(s, &srv)  // OpenAI-compatible

Wiring up with grpc and connectrpc client

Forward MCP tool calls directly to gRPC clients:

testdatamcp.ForwardToTestServiceClient(s, myGrpcClient)

Same for connectrpc:

testdatamcp.ForwardToConnectTestServiceClient(s, myConnectClient)

This directly connects the MCP handler to the client, requiring zero boilerplate.

Extra properties

It's possible to add extra properties to MCP tools, that are not in the proto. These are written into context.

// Enable URL override with custom field name and description
option := runtime.WithExtraProperties(
    runtime.ExtraProperty{
        Name:        "base_url",
        Description: "Base URL for the API",
        Required:    true,
        ContextKey:  MyURLOverrideKey{},
    },
)
// Use with any generated function

testdatamcp.RegisterTestServiceHandler(s, &srv, option)

testdatamcp.ForwardToTestServiceClient(s, client, option)

Tool name prefixing

When registering the same service multiple times (e.g. separate database instances), use WithNamePrefix to namespace tools:

sqlv1mcp.RegisterSQLServiceHandler(s, postgresHandler, runtime.WithNamePrefix("postgres"))
sqlv1mcp.RegisterSQLServiceHandler(s, clickhouseHandler, runtime.WithNamePrefix("clickhouse"))
// Tools: postgres_SQLService_Query, clickhouse_SQLService_Query, ...

Tool naming

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.

To publish a method under a stable, human-chosen name instead, set the (mcp.v1.tool_name) method option:

import "mcp/v1/annotations.proto";
rpc GetEquityResearchReport(GetEquityResearchReportRequest) returns (GetEquityResearchReportResponse) {

  option (mcp.v1.tool_name) = "get_equity_research_report";

}

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.

Migrating from mark3labs-only (pre-v0.2)

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.

1. Server creation