gRPC-MCP

Reference implementation of an MCP transport extension over gRPC using a hybrid model:

• typed hot-path RPCs (Initialize, ListTools, CallTool, etc.),
• bidirectional Connect envelope stream for forward-compatible JSON-RPC traffic.

This repo ships:

• transport specification: SPEC.md,
• protocol definition: proto/mcp/v1/mcp.proto,
• Go reference server/client + auth package,
• Python (grpc.aio) reference server/client + auth package,
• cross-language interop tests.

Why gRPC for MCP

Compared to Streamable HTTP, gRPC gives:

• binary protobuf framing for typed paths,
• long-lived HTTP/2 multiplexed streams,
• built-in backpressure and cancellation propagation,
• straightforward unary + streaming auth interceptors.

Repository layout

• SPEC.md - normative transport extension draft.
• proto/mcp/v1/mcp.proto - MCP and AuthDiscovery services.
• internal/gen/mcp/v1 - generated Go stubs.
• pkg/server - Go MCP server adapter and memory backend.
• pkg/client - Go MCP client wrapper.
• pkg/auth - Go auth policy, interceptor, and credential helpers.
• cmd/mcp-grpc-server / cmd/mcp-grpc-client - Go runnable examples.
• python/mcp_grpc - Python client/server/auth modules.
• python/examples - Python runnable examples.
• python/tests/test_interop.py - Go<->Python interop tests.

Quick start

Prerequisites

• Go 1.25+
• Python 3.11+
• protoc (3.21+)

Generate stubs

make proto

Run Go example

Terminal 1:

go run ./cmd/mcp-grpc-server --addr 127.0.0.1:50051 --auth bearer

Terminal 2:

go run ./cmd/mcp-grpc-client --addr 127.0.0.1:50051 --auth bearer --bearer-token dev-token

Run Python example

Install:

python3 -m pip install -e "./python[dev]"

Terminal 1:

python3 python/examples/server.py --addr 127.0.0.1:50052 --auth bearer

Terminal 2:

python3 python/examples/client.py --addr 127.0.0.1:50052 --auth bearer --bearer-token dev-token

Run interop test suite

go test ./...
cd python && python3 -m pytest -q

Authentication support

Supported modes in both references:

• Bearer token (authorization metadata)
• API key (x-mcp-api-key)
• mTLS mode hook
• Unix-socket peer mode hook

AuthDiscovery/GetMetadata exposes protected resource metadata for OAuth bootstrap.

Note: mTLS in examples is a local demo mode (policy wiring path) rather than full certificate provisioning. For production, use real server certificates, client cert verification, and JWKS-backed token validation.

Transport comparison

Feature	stdio	Streamable HTTP	gRPC-MCP (this repo)
Primary deployment	local subprocess	networked HTTP endpoint	networked gRPC endpoint
Message shape	JSON-RPC newline-delimited	JSON-RPC over POST/SSE	typed protobuf + JSON-RPC envelope
Bidirectional messages	process IO loop	SSE + extra request flow	native bidi stream (Connect)
Streaming progress	possible	SSE events	server-streaming RPC (CallTool)
Auth model	env/local process	MCP HTTP auth framework	metadata + interceptors + AuthDiscovery
Forward compatibility	method-level	method-level	envelope stream fallback

Development notes

• buf.yaml and buf.gen.yaml are provided per plan; generation in this repo uses protoc/grpc_tools via Makefile.
• Go code is formatted with gofmt.
• Python code is validated by py_compile and exercised by pytest interop runs.