grpcmcp

A simple MCP server that will proxy to a grpc backend based on a provided descriptors file or using reflection.

Quick Start

1. Install the binary: `go install .` or `go install github.com/adiom-data/grpcmcp` Ensure the go bin directory is in your PATH.

2. In a terminal, run the example grpc server `go run example/main.go`. This will start a grpc health service on port 8090 with server reflection enabled. Note that this runs on the default port that grpcmcp will connect to.

3. Streamable HTTP Transport In another terminal, run `grpcmcp --hostport=localhost:3000 --reflect`. Specifying `hostport` will use Streamable HTTP by default. The MCP endpoint will be served at `http://localhost:3000/mcp`.

4. Legacy SSE Transport For older clients, run `grpcmcp --hostport=localhost:3000 --transport=sse --reflect`. The SSE endpoint will be served at `http://localhost:3000/sse`.

5. STDIN Transport Set up the MCP config. e.g.

"grpcmcp": {
    "command": "grpcmcp",
    "args": ["--reflect"]
}

Options / Features

`grpcmcp --help` for a full list of options.

• `hostport` string - When set, serve MCP over HTTP, and use this as the server host:port.

• `transport` string - Transport to use when `hostport` is set. Defaults to `http` for Streamable HTTP at `/mcp`. Set to `sse` for the legacy SSE transport at `/sse`.

• `descriptors` string - Specify file location of the protobuf definitions generated from `buf build -o protos.pb` or `protoc --descriptor_set_out=protos.pb` instead of using gRPC reflection.

• `reflect` - If set, use reflection to retrieve gRPC endpoints instead of descriptor file.

• `url` string - Specify the url of the backend server.

• `services` string - Comma separated list of fully qualified gRPC service names to filter.

• `bearer` string - Token to attach in an `Authorization: Bearer` header.

• `bearer-env` string - Environment variable for token to attach in an `Authorization: Bearer` header. Overrides `bearer`.

• `header` string (repeatable) - Headers to add in `Key: Value` format.

• `string64` - If set, expose 64-bit protobuf integer fields (`int64`, `uint64`, `sint64`, `fixed64`, `sfixed64`) as strings only in MCP JSON schemas. This avoids precision ambiguity for JavaScript-based clients and agents. By default, schemas continue to allow either JSON numbers or strings for compatibility.

grpcmcp currently exposes unary gRPC methods as MCP tools. Backend gRPC client-streaming, server-streaming, and bidi-streaming methods are skipped. This is separate from MCP transports: Streamable HTTP and legacy SSE are supported for client connections to grpcmcp.

Library Usage

grpcmcp can also be embedded as a Go library. The library accepts a descriptor set directly, so applications can decide how to load descriptors and how to wrap the MCP HTTP handler.

descriptors, err := grpcmcp.LoadDescriptorsFromReflection(ctx, backendURL, headers, false)
if err != nil {
    return err
}

srv, err := grpcmcp.NewServer(grpcmcp.Config{
    ServerName:  "gRPC MCP Server",
    Version:     "1.0.0",
    BaseURL:     backendURL,
    Descriptors: descriptors,
    Headers:     grpcmcp.StaticHeaders(headers),
})
if err != nil {
    return err
}

handler := server.NewStreamableHTTPServer(srv)

To route backend calls through a custom transport, provide `HTTPClient`. For example, an embedded application can use an in-memory HTTP transport such as `go.akshayshah.org/memhttp` by passing the in-memory server's URL and client:

backend, err := memhttp.New(backendHandler)
if err != nil {
    return err
}
defer backend.Close()

srv, err := grpcmcp.NewServer(grpcmcp.Config{
    BaseURL:     backend.URL(),
    HTTPClient:  backend.Client(),
    Descriptors: descriptors,
})

For dynamic backend auth, provide a `ToolHeaderProvider`. The full `mcp.CallToolRequest` is available, including inbound HTTP headers supplied by supported MCP transports.

srv, err := grpcmcp.NewServer(grpcmcp.Config{
    BaseURL:     backendURL,
    Descriptors: descriptors,
    Headers: func(ctx context.Context, req mcp.CallToolRequest) (http.Header, error) {
        h := make(http.Header)
        h.Set("Authorization", req.Header.Get("Authorization"))
        return h, nil
    },
})

Inbound MCP authentication should be handled by wrapping the HTTP handler with standard Go middleware. Outbound backend authentication is controlled by the configured header provider.

Help

Join our Discord at https://discord.gg/hDjx3DehwG