grpc -gateway

The grpc-mcp-gateway project provides a protoc plugin and runtime that turns gRPC services annotated with MCP options into fully compliant MCP servers. This gateway acts as a bridge: it forwards MCP tool calls from an MCP client to your remote gRPC service, while handling MCP-specific flows such as prompts, elicitation, progress updates, and resource discovery. Use it to expose your gRPC-based service as an MCP server so clients like Claude Desktop or MCP Inspector can list tools, invoke them with structured inputs, and receive results in MCP-native JSON formats. The gateway specifically supports forwarding MCP tool invocations to a remote gRPC server, enabling you to keep your business logic in your existing gRPC service while leveraging MCP tooling, prompts, and elicitation at the orchestration layer. To use it, deploy the gateway alongside a gRPC service that implements the generated MCP stubs and ensure your proto annotations are configured for tools, prompts, resources, and elicitation as needed. Clients will connect to the MCP server exposed by the gateway, which then communicates with your gRPC backend to execute tools and return results.

Prerequisites:

• Docker installed on the host, or a container runtime capable of running the image
• Optional: Access to a remote gRPC server implementing the generated MCP stubs

Installation steps:

1. Pull and run the gateway container (example using Docker):

   docker run -i machanirobotics/grpc-mcp-gateway:latest

   Note: If you have a specific image tag or registry, replace the image name accordingly.

2. If you prefer to build from source (Go-based workflow), ensure Go is installed and run the protoc plugin as part of your build process, then run your generated MCP server as you would any Go binary. See the repository README for details on generating MCP servers from your .proto files using protoc-gen-mcp.

3. Ensure your gRPC service is reachable by the gateway (proper host/port) and that your proto annotations include the desired MCP options (tools, prompts, resources, elicitation).

4. Validate the gateway is serving MCP calls by connecting an MCP client (e.g., MCP Inspector) to the gateway’s MCP endpoint and listing tools.

Tips and common issues:

• If you use the docker image, ensure the gateway has network access to your gRPC service. You may need to set a GRPC_TARGET or similar environment variable based on how you configure the gateway to reach your backend.
• Configure prompts, elicitation, and resources in your protobuf annotations to leverage MCP features like confirmations and schema-validated inputs.
• For progress streaming, ensure your gRPC service supports MCPProgress messages if you plan to expose long-running tools.
• If you’re using a custom environment, you may need to expose the MCP server on a public or private endpoint so MCP clients can connect.
• When upgrading, re-generate stubs if you’ve updated your proto annotations, and verify that pre-compiled MCP protos (mcp protobuf types) are compatible with your client and gateway versions.