ggRMCP - gRPC to MCP Gateway

🎯 What is ggRMCP?

ggRMCP is a high-performance Go-based gateway that converts gRPC services into MCP-compatible tools, allowing AI models like Claude to directly call your gRPC services. It acts as a translator between the gRPC world and the MCP ecosystem, providing seamless integration without requiring modifications to existing gRPC services.

ggRMCP uses gRPC reflection to discover available services and methods, generating MCP tools dynamically. This enables AI applications to interact with gRPC services as if they were native tools, enhancing the capabilities of AI models with real-time data access and processing.

ggRMCP can also be configured to read FileDescriptorSet files, enabling it to extract comments and documentation from protobuf definitions for a richer AI application experience.

This allows you to leverage existing gRPC services without needing to rewrite or adapt them for AI use cases, making it easier to integrate AI capabilities into your applications.

🚨 Disclaimer

ggRMCP is an experimental project and is not yet production-ready.

Deployment Patterns:

🐳 Sidecar Proxy: Deploy alongside your gRPC service in any language (Java, Python, C++, Go, etc.)
🌐 Centralized Gateway: Single instance serving multiple gRPC backends

The transcoding is performed in real-time with no modifications required to existing gRPC services. As a language-agnostic sidecar, ggRMCP works with gRPC services written in any language that supports gRPC reflection.

📋 Model Context Protocol (MCP)

MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications - it provides a standardized way to connect AI models to different data sources and tools.

How ggRMCP Uses MCP

Tool Registration: Each gRPC method becomes an MCP tool
Schema Definition: Protobuf schemas are converted to JSON schemas
Request/Response Handling: Automatic translation between JSON and protobuf
Error Handling: Standardized error responses following MCP specifications
Header Forwarding: HTTP headers are securely forwarded to gRPC services

🌟 Key Features

Core Capabilities

🌍 Language Agnostic: Works as a sidecar with gRPC services in any language
🔌 Seamless Integration: Connect existing gRPC services to AI applications without modification
🚀 Sidecar Ready: Deploy alongside your service containers with zero code changes
📡 Dynamic Service Discovery: Automatic gRPC service discovery using gRPC server reflection or FileDescriptorSet
🔄 Real-time Tool Generation: Dynamic MCP tool generation from gRPC service definitions with comment extraction
📝 Schema Validation: Automatic request/response validation using protobuf schemas
🧠 Session Management: Stateful session handling for complex AI interactions
📨 Header Forwarding: Configurable HTTP header forwarding to gRPC services with security filtering
📋 FileDescriptorSet Support: Rich tool schemas with comments and documentation from .binpb descriptor files

🏗️ Architecture

graph TB
    subgraph "Client Layer"
        A[MCP Client<br/>Claude AI]
    end
    
    subgraph "ggRMCP Gateway"
        B[HTTP Server]
        C[MCP Protocol Handler]
        D[Session Manager]
        E[Service Discoverer]
        F[Connection Manager]
        G[McpTool Builder]
        H[Reflection Client]
    end
    
    subgraph "gRPC Services"
        I[Service A]
        J[Service B]
        K[Service N...]
    end
    
    A -->|HTTP/JSON-RPC| B
    B --> C
    C --> D
    C --> E
    E --> F
    E --> G
    E --> H
    F -->|gRPC Connection| I
    F -->|gRPC Connection| J
    F -->|gRPC Connection| K
    H -->|Reflection API| I

Core Components

| Component | Location | Purpose | |-----------|----------|---------| | Connection Manager | pkg/grpc/connection.go | Manages gRPC connections with health checking and reconnection | | Service Discoverer | pkg/grpc/discovery.go | Discovers and manages gRPC services | | Reflection Client | pkg/grpc/reflection.go | Handles gRPC reflection API for service discovery | | MCP Handler | pkg/server/handler.go | Implements MCP protocol over HTTP | | Session Manager | pkg/session/manager.go | Manages user sessions with rate limiting | | Tool Builder | pkg/tools/builder.go | Generates JSON schemas from protobuf definitions | | Header Filter | pkg/headers/filter.go | Filters and forwards HTTP headers to gRPC services | | Configuration | pkg/config/config.go | Centralized configuration management |

🚀 Deployment Patterns

Sidecar Pattern

Deploy ggRMCP as a sidecar container alongside your gRPC service:

graph LR
    subgraph "Pod/Container Group"
        subgraph "Your Service"
            A[gRPC Service<br/>Any Language]
        end
        subgraph "Sidecar"
            B[ggRMCP Gateway]
        end
        A -.->|localhost:50051| B
    end
    
    C[AI Client<br/>Claude/MCP] -->|HTTP/JSON-RPC<br/>:50053| B

Benefits:

✅ Zero code changes to existing services
✅ Works with any language (Java, Python, C++, Go, etc.)
✅ Isolated from service failures
✅ Independent scaling and updates

Centralized Gateway Pattern

Single ggRMCP instance serving multiple gRPC backends:

graph TB
    A[AI Client] -->|HTTP/JSON-RPC| B[ggRMCP Gateway]
    
    B -->|gRPC| C[User Service<br/>Java]
    B -->|gRPC| D[Order Service<br/>Python]
    B -->|gRPC| E[Payment Service<br/>Go]
    B -->|gRPC| F[Inventory Service<br/>C++]

🏁 Quick Start

Prerequisites

Go 1.23 or higher
A running gRPC server with reflection enabled (example service provided)
make for building (optional)
protoc for generating FileDescriptorSet files (optional)

Option A: Quick Start with Hello Service Example

The fastest way to test ggRMCP is using the included hello-service example:

1. Clone and Build

git clone https://github.com/aalobaidi/ggRMCP
cd ggRMCP
go mod download
go build -o build/grmcp ./cmd/grmcp

2. Start the Hello Service

cd examples/hello-service

# Build and run the hello service (default port 50051)
make run

# OR manually:
# go build -o hello-service .
# ./hello-service

# OR run on a custom port:
# ./hello-service --port=50052

This starts a gRPC service on localhost:50051 (or custom port) with reflection enabled and a SayHello method.

3. Start ggRMCP Gateway

Choose one of the following options:

Option a: Using gRPC Reflection

# From the project root
./build/grmcp --grpc-host=localhost --grpc-port=50051 --http-port=50053 --log-level=debug

Option b: Using FileDescriptorSet (Enhanced Schemas with Comments)

# Generate the FileDescriptorSet with comments
cd examples/hello-service
make descriptor

# Start gateway with descriptor file (from project root)
cd ../../
./build/grmcp --grpc-host=localhost --grpc-port=50051 --http-port=50053 --descriptor=examples/hello-service/build/hello.binpb --log-level=debug

4. Test the Gateway

# Check health
curl http://localhost:50053/health

# List available tools (should show hello_helloservice_sayhello)
curl -X POST http://localhost:50053/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call the SayHello method
curl -X POST http://localhost:50053/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"hello_helloservice_sayhello","arguments":{"name":"World","email":"test@example.com"}}}'

5. Hello Service Makefile Commands

cd examples/hello-service

make install-tools # Install protobuf tools (protoc-gen-go, protoc-gen-go-grpc)
make setup         # Install tools and generate protobuf files  
make build         # Build the hello service binary
make run           # Build and run the service
make proto         # Generate protobuf Go files
make descriptor    # Generate FileDescriptorSet for ggRMCP
make clean         # Clean build artifacts
make help          # Show available targets

🔗 Connect to Claude Desktop

Install MCP remote client:

npm install -g mcp-remote

Configure Claude Desktop - Add to your MCP configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "grpc-gateway": {
      "command": "mcp-remote",
      "args": ["http://localhost:50053"],
      "env": {}
    }
  }
}

Restart Claude Desktop to apply the configuration.
Test the connection - Claude should now have access to your gRPC service methods as tools. You can:
- Ask Claude to list available tools
- Call specific gRPC methods
- Handle complex request/response data

✅ Verify Everything Works

# Check gateway health
curl http://localhost:50053/health

# List available tools via MCP
curl -X POST http://localhost:50053/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Test calling the hello service
curl -X POST http://localhost:50053/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc"

GgRMCP

Install / Use

README