mcp-grpc-agent

A gRPC-to-MCP bridge that exposes domain services as tools for AI agents, backed by protobuf descriptors.

Deployed per functional domain, each instance translates gRPC unary methods into MCP tools that can be invoked by the central MCP gateway via Bedrock.

Origin

Based on adiom-data/grpcmcp (Apache-2.0), restructured for internal deployment patterns.

Configuration

All configuration is via environment variables with the MCP_ prefix.

Variable	Required	Default	Description
MCP_BACKEND_URL	✓		gRPC backend URL (e.g. http://book-gateway.book:50051)
MCP_DESCRIPTOR_PATH	*		Path to compiled protobuf descriptor set (.pb file)
MCP_USE_REFLECTION	*	false	Use gRPC reflection instead of descriptor file
MCP_SERVICES			Comma-separated list of fully qualified service names to expose. If empty, all services in the descriptor are exposed.
MCP_SERVER_NAME		mcp-grpc-agent	MCP server name advertised to clients
MCP_SERVER_VERSION		1.0.0	Version string advertised to clients
MCP_TRANSPORT		http	MCP transport: http (Streamable HTTP) or sse
MCP_LISTEN_ADDRESS		0.0.0.0:8080	MCP endpoint address
MCP_HEALTH_ADDRESS		0.0.0.0:8081	Health probe address
MCP_METRICS_ADDRESS		0.0.0.0:8082	Prometheus metrics address
MCP_BEARER_TOKEN			Static bearer token for backend auth
MCP_BEARER_TOKEN_ENV			Env var name containing bearer token (overrides MCP_BEARER_TOKEN)
MCP_USE_CONNECT		false	Use Connect protocol instead of gRPC
MCP_STRING64		false	Expose 64-bit integer fields as strings in JSON schemas

* One of MCP_DESCRIPTOR_PATH or MCP_USE_REFLECTION must be set.

Ports

Port	Path	Purpose
8080	/mcp	MCP Streamable HTTP endpoint
8081	/liveness, /readiness	Kubernetes health probes
8082	/metrics	Prometheus metrics

How it works

1. On startup, loads protobuf descriptors from a file or via gRPC reflection
2. Registers each unary RPC method as an MCP tool (streaming methods are skipped)
3. Tool names follow the pattern <package>_<service>__<method> (dots replaced with underscores)
4. Tool descriptions are sourced from proto source comments
5. When a tool is called, the agent marshals the JSON arguments into a protobuf message and calls the backend via gRPC

Building

go build -o mcp-grpc-agent .

Docker

docker build -t mcp-grpc-agent .

Local development

chmod +x run.sh
./run.sh

Generating descriptor files

Descriptors are generated during CI and deployed as ConfigMaps. To generate locally:

protoc --descriptor_set_out=descriptors.pb --include_imports \
  --proto_path=. proto/**/*.proto

Or with buf:

buf build -o descriptors.pb

Architecture

MCP Gateway (Bedrock)
    │
    ▼ MCP tool call
┌─────────────────────┐
│   mcp-grpc-agent    │  ← one per functional domain
│   (this service)    │
└──────────┬──────────┘
           │ gRPC unary call
           ▼
┌─────────────────────┐
│  domain-gateway     │  (e.g. book-gateway.book:50051)
│  (existing service) │
└─────────────────────┘