v0.2.0 - stdio → gRPC Bridge

The bridge release. mcp-grpc now ships cmd/mcp-grpc-bridge, a transparent stdio → gRPC bridge that lets existing stdio MCP clients — Claude Desktop, Cursor, and anything else that speaks MCP over stdio — reach a remote MCP server over a gRPC connection, with TLS and mTLS. This is the connectivity story the transport was built to enable.

What's new

The bridge is a local MCP server on its stdio side and an MCP client on its gRPC side, in one process. It relays JSON-RPC messages in both directions and never interprets MCP semantics, so it works for any MCP traffic (initialize, tools/*, resources/*, notifications, …) without tracking sessions or schemas. Internally it exercises the v0.1 ClientTransport over a real network with a real MCP client on the other end.

Why it matters

Thousands of people already run stdio MCP clients; almost nobody has a gRPC-native client looking for an MCP server. The bridge meets that reality: point your stdio client at the bridge binary and it dials a remote gRPC MCP backend for you — over TLS. A bridge that crosses the network in plaintext is not deployable, so TLS/mTLS is the part that turns the in-memory v0.1 proof into something usable.

Added

• cmd/mcp-grpc-bridge: a stdio → gRPC bridge. It opens a stdio mcp.Connection and a gRPC mcp.Connection (via transport.ClientTransport) and pumps jsonrpc.Message values between them in both directions, ending cleanly when either side closes.
• TLS and mTLS on the bridge's gRPC connection via -tls, -ca, -cert, -key, -server-name, and -insecure-skip-verify. TLS minimum version is 1.2; -cert/-key must be supplied together for mTLS.
• End-to-end test driving a real MCP client → bridge sub-process → echo MCP server over a real TCP listener with TLS (certificates generated in-test), plus a unit test of the relay pump asserting both-direction relay and clean close.

Changed

• README documents the bridge (plaintext, TLS, mTLS) and reframes the project's lasting value as connectivity rather than a scaffold.

Not in this release

• The symmetric direction (gRPC → stdio, exposing a stdio MCP server over gRPC) and gRPC ↔ Streamable HTTP bridging.
• Interceptors (log/metrics), session-id/auth via gRPC metadata, and fine-grained keepalive/deadline tuning — deferred to a following increment.

Usage

go install github.com/P4ST4S/mcp-grpc/cmd/mcp-grpc-bridge@v0.2.0

# TLS, verifying the server against a CA bundle:
mcp-grpc-bridge -addr mcp.example.com:7777 -tls -ca ca.pem

# mTLS with a server-name override:
mcp-grpc-bridge -addr 10.0.0.5:7777 -tls -ca ca.pem \
    -cert client.pem -key client-key.pem -server-name mcp.example.com

Install

go get github.com/P4ST4S/mcp-grpc@v0.2.0

See the README for wiring the bridge into a stdio MCP client.

v0.1.0 - gRPC Transport

First release of mcp-grpc: a pluggable gRPC transport for the Model Context Protocol in Go. It carries MCP JSON-RPC traffic over a single gRPC bidirectional stream, plugging directly into the official go-sdk mcp.Transport / mcp.Connection interfaces. This is a library, not a binary.

What's new

mcp-grpc lets an MCP client and server speak over a gRPC bidi stream instead of stdio or Streamable HTTP. A ClientTransport and a ServerTransport implement the SDK's mcp.Transport, mapping Connection.Read/Write 1:1 onto stream.Recv/stream.Send of opaque JSON-RPC frames.

The MCP maintainers have committed to exactly two official transports (STDIO, Streamable HTTP) and to making custom transports easier; gRPC will be a custom transport. v0.1 is the transport scaffold — the release that will matter is v0.2 (the bridge/proxy), whose value is connectivity (gRPC-native clients ↔ MCP JSON-RPC servers).

Why it matters

Carrying MCP over gRPC unlocks HTTP/2 multiplexing, flow-control backpressure, and the gRPC operational surface (keepalive, deadlines, TLS/mTLS, interceptors) for MCP sessions — while the opaque bytes payload keeps the transport fully decoupled from the evolving MCP schema and reuses the SDK's hardened JSON-RPC (de)serialization.

Added

• transport.ClientTransport and transport.NewHandler(*mcp.Server) implementing the SDK transport interfaces over a gRPC bidi stream.
• mcp.grpc.v1.MCPTransport proto contract with an opaque Frame { bytes payload }, generated via Buf into the public mcpgrpcv1/ package.
• Serialized writes (sync.Mutex around stream.Send, teardown outside the lock) — mcp.Connection.Write may be called concurrently but gRPC forbids concurrent Send.
• Cancellable server reads via a receive-pump goroutine + select, so Close and per-read deadlines unblock a waiting Read (cancelling a child context does not unblock stream.Recv).
• Asymmetric Close: client cancels its call context, server signals its blocking handler to return. Both idempotent and concurrency-safe.
• gRPC ↔ transport error mapping and clean io.EOF translation for graceful close.
• Runnable echo example (examples/server, examples/client) and a shared examples/echo package.

Tests

• End-to-end interop over bufconn (real in-memory HTTP/2): initialize → tools/list → tools/call echo.
• Concurrent N-writers test asserting message integrity (not just -race): every frame decodes back to a distinct message.
• FuzzFrameDecode over arbitrary payloads — never panics.
• Clean-close test proving the server handler's Wait() returns when the stream closes.

Not in v0.1

• No cmd/mcp-grpc-bridge proxy (v0.2).
• No typed-per-method protobuf payload (opaque JSON-RPC bytes by design).
• No Dial helper — the caller provides and owns the *grpc.ClientConn.
• No session multiplexing, no distributed stateless mode.
• TLS/mTLS over a real TCP listener is exercised in v0.2.

Requirements

• Go 1.25+
• github.com/modelcontextprotocol/go-sdk v1.6.1
• google.golang.org/grpc v1.81.1, google.golang.org/protobuf v1.36.11

Install

go get github.com/P4ST4S/mcp-grpc@v0.1.0

See the README for server and client usage.