Grpc Mcp Gateway

grpc-mcp-gateway

gRPC ↔ MCP Bridge — Generate MCP servers directly from protobufs enabling seamless AI-native interfaces for existing services

Overview

grpc-mcp-gateway is a protoc plugin and runtime that automatically converts your gRPC services into MCP-compatible servers.

gRPC → MCP proxy generator following the MCP Specification.

Instead of rewriting APIs for AI systems, you can expose your existing gRPC infrastructure as:

• Tools → callable functions for agents
• Prompts → structured interaction templates
• Resources → retrievable context/data
• Elicitation → dynamic input flows

Built with a spec-first approach, it ensures full compliance with the Model Context Protocol while keeping your system strongly typed and scalable.

Open-sourced by The Protobuf Project, this project bridges traditional backend systems with AI-native platforms.

A protoc plugin and runtime that turns any gRPC service into a fully spec-compliant Model Context Protocol server — tools, prompts, resources, and elicitation — in Go, Python, Rust, and C++.

Features

• Multi-language — Generate MCP server code for Go, Python, Rust, and C++ from a single .proto file
• Tools — Every unary RPC becomes an MCP tool with a JSON Schema derived from the protobuf request message
• Prompts — Attach prompt templates to RPCs with schema-validated arguments via (mcp.prompt)
• Field descriptions — Add (mcp.field) = { description: "..." } to message fields for schema descriptions
• Enum descriptions — Add (mcp.enum) and (mcp.enum_value) for enum-level and per-value descriptions in the schema
• Progress — Use gRPC server streaming with mcp.MCPProgress for MCP progress notifications on long-running tools
• Resources — Auto-detect MCP resources from google.api.resource annotations
• Elicitation — Generate confirmation dialogs before tool execution via (mcp.elicitation)
• Transports — stdio, SSE, and streamable-http — run multiple concurrently in a single process
• gRPC Gateway — Forward MCP tool calls to a remote gRPC server (Go)
• Published Protos — Import the MCP annotations from buf.build/the-protobuf-project/mcp and generate the types in your own client

| Language | Generated File | Example | | ---------- | ---------------------------------- | ------------------------------------ | | Go | *_service.pb.mcp.go | [examples/go](examples/go) | | Python | *_service_pb2_mcp.py | [examples/python](examples/python) | | Rust | *_service.mcp.rs | [examples/rust](examples/rust) | | C++ | *_service.mcp.h/cc + Rust bridge | [examples/cpp](examples/cpp) |

Architecture

graph LR
    Proto[".proto + MCP annotations"] -->|buf generate| GenGo["Go MCP stubs"]
    Proto -->|buf generate| GenPy["Python MCP stubs"]
    Proto -->|buf generate| GenRs["Rust MCP stubs"]
    Proto -->|buf generate| GenCpp["C++ MCP bridge"]
    GenGo --> GoSrv["Go Server"]
    GenPy --> PySrv["Python Server"]
    GenRs --> RsSrv["Rust Server"]
    GenCpp --> CppSrv["C++ Server"]
    GoSrv -->|stdio / SSE / streamable-http| Client["MCP Client / LLM"]
    PySrv -->|stdio / SSE / streamable-http| Client
    RsSrv -->|stdio / SSE / streamable-http| Client
    CppSrv -->|stdio / streamable-http| Client

How It Works

sequenceDiagram
    participant LLM as LLM / MCP Client
    participant MCP as MCP Server (generated)
    participant gRPC as gRPC Service (your impl)

    LLM->>MCP: tools/list
    MCP-->>LLM: [{name, description, inputSchema}, ...]
    LLM->>MCP: tools/call (tool_name, args)
    Note over MCP: elicitation (if configured)
    MCP->>gRPC: RPC method(request)
    gRPC-->>MCP: response
    MCP-->>LLM: tool result (JSON)

1. Annotate your .proto services with MCP options (tools, prompts, resources, elicitation).
2. Generate MCP server code with buf generate using protoc-gen-mcp.
3. Implement your gRPC service logic as usual.
4. Serve — the generated code starts an MCP server on your chosen transport(s).
5. Connect — MCP clients (Claude Desktop, MCP Inspector, custom LLM agents) discover and invoke your tools.

Install

Plugin

go install github.com/the-protobuf-project/grpc-mcp-gateway/plugin/cmd/protoc-gen-mcp@latest

Or download a binary from GitHub Releases.

MCP annotation types

The MCP annotation types (mcp.*) are needed at runtime so generated code can resolve its imports — just like googleapis-common-protos for Google API types.

• Go — pre-compiled and shipped as part of this module:

[mcp/protobuf/mcppb](mcp/protobuf/README.md) (go get github.com/the-protobuf-project/grpc-mcp-gateway/mcp/protobuf/mcppb).

• Other languages — add the published Buf module as a dependency and

generate the types in your own client (see [Quick Start](#quick-start) below). Nothing extra to install: the annotations come from buf.build/the-protobuf-project/mcp.

Quick Start

1. Add the proto dependency

# buf.yaml
version: v2
deps:
  - buf.build/googleapis/googleapis
  - buf.build/the-protobuf-project/mcp

buf dep update

2. Annotate your proto

syntax = "proto3";
package todo.v1;

import "mcp/protobuf/annotations.proto";

service TodoService {
  option (mcp.service) = {
    app: {
      name: "Todo App"
      version: "1.0.0"
      description: "A simple todo management application"
    }
  };

  rpc CreateTodo(CreateTodoRequest) returns (Todo) {
    option (mcp.tool) = {
      description: "Creates a new todo item."
    };
    option (mcp.elicitation) = {
      message: "Please confirm the todo details before creating."
      schema: "todo.v1.CreateTodoConfirmation"
    };
  }

  rpc GetTodo(GetTodoRequest) returns (Todo) {
    option (mcp.tool) = {
      description: "Retrieves a todo by resource name."
    };
    option (mcp.prompt) = {
      name: "summarize_todos"
      description: "Summarize all pending todo items for a user"
      schema: "todo.v1.SummarizeTodosArgs"
    };
  }
}

// Enum with descriptions for MCP tool schema
enum Priority {
  option (mcp.enum) = { description: "Priority level for a todo item." };

  PRIORITY_UNSPECIFIED = 0 [(mcp.enum_value) = { description: "Unspecified; use default priority." }];
  PRIORITY_LOW = 1 [(mcp.enum_value) = { description: "Low priority; can be done when convenient." }];
  PRIORITY_MEDIUM = 2 [(mcp.enum_value) = { description: "Normal priority; default for most todos." }];
  PRIORITY_HIGH = 3 [(mcp.enum_value) = { description: "High priority; should be done soon." }];
  PRIORITY_URGENT = 4 [(mcp.enum_value) = { description: "Urgent; do first." }];
}

3. Generate code

# buf.gen.yaml
version: v2
plugins:
  # --- Go ---
  - local: protoc-gen-go
    out: generated/go
    opt: [module=example/generated/go]
  - local: protoc-gen-mcp
    out: generated/go
    opt: [lang=go, module=example/generated/go]

  # --- Python ---
  - remote: buf.build/protocolbuffers/python
    out: generated/python
  - local: protoc-gen-mcp
    out: generated/python
    opt: [lang=python, paths=source_relative]

  # --- Rust ---
  - remote: buf.build/community/neoeinstein-prost
    out: generated/rust
  - local: protoc-gen-mcp
    out: generated/rust
    opt: [lang=rust, paths=source_relative]

  # --- C++ (Rust bridge + C++ gRPC client) ---
  - local: protoc-gen-mcp
    out: generated/cpp
    opt: [lang=cpp, paths=source_relative]

buf generate

4. Run with MCP Inspector

# Go
cd examples/go/stdio && go run .
npx @modelcontextprotocol/inspector -- go run .

# Python
cd examples/python
npx @modelcontextprotocol/inspector -- uv run python stdio/main.py

# Rust
cd examples/rust && cargo build --bin stdio
npx @modelcontextprotocol/inspector -- ./target/debug/stdio

# C++
cd examples/cpp && make
MCP_TRANSPORT=stdio npx @modelcontextprotocol/inspector -- ./server

MCP Annotations

All annotations are imported from mcp/protobuf/annotations.proto (BSR).

Service-level: mcp.service

Defines app metadata for the MCP server:

option (mcp.service) = {
  app: { name: "My App" version: "1.0.0" description: "..." }
};

Tool: mcp.tool

Override auto-generated tool name or description:

rpc CreateItem(CreateItemRequest) returns (Item) {
  option (mcp.tool) = {
    name: "custom_tool_name"
    description: "Custom description for LLMs."
  };
}

Prompt: mcp.prompt

Attach a prompt template to an RPC. The schema references a proto message whose fields become prompt arguments:

rpc GetItem(GetItemRequest) returns (Item) {
  option (mcp.prompt) = {
    name: "summarize_items"
    description: "Summarize all items"
    schema: "mypackage.SummarizeItemsArgs"
  };
}

Elicitation: mcp.elicitation

Request user confirmation before executing a tool. The schema references a proto message whose fields become the confirmation form:

rpc DeleteItem(DeleteItemRequest) returns (google.protobuf.Empty) {
  option (mcp.elicitation) = {
    message: "Are you sure you want to delete this item?"
    schema: "mypackage.DeleteConfirmation"
  };
}

Elicitation is supported in all three languages with graceful degradation — if the client doesn't support elicitation, the tool proceeds without confirmation.

Field: mcp.field

Add JSON Schema metadata to a message field for the MCP tool inputSchema:

message User {
  string name = 1 [
    (google.api.field_behavior) = IDENTIFIER,
    (mcp.field) = {
      description: "The resource name of the user. You can parse the user id from the resource name."
      examples: "users/alice"
      examples: "users/bob"
      format: "uri"           // optional: override format (uri, email, uuid, etc.)
      deprecated: false       // optional: mark field as deprecated
    }
  ];
}

• description — Human-readable description (recommended for LLMs)
• examples — Example values to guide LLMs (repeated)
• deprecated — Mark the field as deprecated in the schema
• format — JSON Schema format override (e.g. uri, email, uuid)

Enum: mcp.enum and mcp.enum_value

Add descriptions to enum types and individual enum values for the MCP tool inputSchema:

enum Priority {
  option (mcp.enum) = { description: "Priority level for a todo item." };

  PRIORITY_UNSPECIFIED = 0 [(mcp.enum_value) = { description: "Unspecified; use default priority." }];
  PRIORITY_LOW = 1 [(mcp.enum_value) = { description: "Low priority; can be done when convenient." }];
  PRIORITY_MEDIUM = 2 [(mcp.enum_value) = { description: "Normal priority; default for most todos." }];
  PRIORITY_HIGH = 3 [(mcp.enum_value) = { description: "High priority; should be done soon." }];
  PRIORITY_URGENT = 4 [(mcp.enum_value) = { description: "Urgent; do first." }];
}

The schema includes:

• description — Combined enum-level and per-value descriptions
• enumDescriptions — Map of value name → description for structured access

For enum fields, enum descriptions take precedence over (mcp.field) description when both are present.

Progress (server streaming)

For long-running operations, use gRPC server streaming with mcp.MCPProgress to send progress notifications to MCP clients. Define a stream response with a oneof:

import "mcp/protobuf/progress.proto";

message CreateTodoStreamChunk {
  oneof payload {
    mcp.MCPProgress progress = 1;
    Todo result = 2;
  }
}

rpc CreateTodo(CreateTodoRequest) returns (stream CreateTodoStreamChunk);

The plugin auto-generates tool handlers that send MCP notifications/progress for each progress chunk and return the final result. Progress is supported when using ForwardTo*MCPClient (gRPC forwarding). Clients request progress by including progressToken in params._meta.

Progress and timeouts: Long-running requests that send progress must not time out. The gateway uses ReadTimeout: 0 and WriteTimeout: 0 by default so streaming progress is never interrupted. If you set WriteTimeout in MCPServerConfig, use 0 or a very high value for progress-enabled tools. MCP clients (e.g. Inspector) may have their own timeout; enable timeout reset on progress when available (MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS). If you see "MCP error -32001: Maximum total timeout exceeded", the client has a hard cap on total request time (Inspector default: 60s). Increase it, e.g. MCP_REQUEST_MAX_TOTAL_TIMEOUT=300000 (5 min, in ms).

Resources

Resources are auto-detected from google.api.resource annotations on proto messages. No additional MCP annotation is needed.

Project Structure

grpc-mcp-gateway/
├── go.mod                          # Single Go module
├── go.work                         # Workspace (root + examples)
├── proto/                          # Publishable buf module (BSR)
│   └── mcp/protobuf/              # MCP annotation .proto source files
├── mcp/protobuf/                  # Pre-compiled Go proto types
│   └── mcppb/                     # Go (.pb.go) — see [mcp/protobuf/README.md](mcp/protobuf/README.md)
├── runtime/                       # Go runtime — [README](runtime/README.md)
├── plugin/
│   ├── cmd/protoc-gen-mcp/        # Plugin binary (go install target)
│   └── generator/                 # Code generation (Go, Python, Rust, C++)
│       └── templates/             # go.tpl, python.tpl, rust.tpl, cpp/*.tpl
├── examples/                      # Separate module with replace directive
│   ├── proto/                     # TodoService + CounterService definitions
│   ├── go/                        # Go examples (http, stdio, sse, grpc-gateway, counter)
│   ├── python/                    # Python examples (http, stdio, sse)
│   ├── rust/                      # Rust examples (http, stdio, sse)
│   └── cpp/                       # C++ example (Make, gRPC + MCP via Rust bridge)
└── .github/workflows/             # CI + release pipelines

Plugin Options

| Option | Values | Description | | ---------------- | ----------------------------- | -------------------------------------------------------- | | lang | go, python, rust, cpp | Target language for generated code | | module | Go module path | Go module prefix for output path resolution | | package_suffix | any string (Go only) | Sub-package suffix for generated .pb.mcp.go files | | paths | source_relative | Place output relative to the proto source (Python, Rust) |

Generated Code

For each proto service, the plugin generates:

| Feature | Go | Python | Rust | C++ | | ------------------- | --------------------------------------------------- | -------------------------------------- | --------------------------------- | -------------------------------- | | Tools (per RPC) | s.AddTool(...) | @server.call_tool() | ServerHandler::call_tool() | TodoServiceMcpImpl (cxx FFI) | | Prompts | s.AddPrompt(...) | @server.get_prompt() | `ServerHandler::

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: the-protobuf-project
• Source: the-protobuf-project/grpc-mcp-gateway
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.