protoc-gen-connect-go-mcp

A Protocol Buffers compiler plugin that generates MCP (Model Context Protocol) server code from gRPC service definitions.

Overview

protoc-gen-connect-go-mcp is a protoc plugin that automatically generates MCP server implementations from your existing gRPC service definitions. It creates ready-to-use MCP tools that can be integrated into MCP-compatible applications.

Features

• Automatic MCP Server Generation: Converts gRPC services to MCP server implementations
• InputSchema Generation: Automatically generates JSON Schema for tool parameters from proto message fields
• Official MCP SDK: Uses the official MCP Go SDK for maximum compatibility
• Flexible Package Organization: Supports custom package suffixes for better code organization
• Multi-line Comment Support: Preserves formatting in proto file comments for better tool descriptions
• Connect-Go Compatible: Works alongside protoc-gen-connect-go for full gRPC support
• Standard Endpoint Paths: Uses {package}.{Service}/{Method} format for Connect-Go compatibility

Installation

Prerequisites

• Go 1.23 or later
• Protocol Buffers compiler (protoc)
• buf CLI tool (recommended)

Install

go install github.com/yoshihiro-shu/connect-go-mcp/cmd/protoc-gen-connect-go-mcp@latest

Usage

With buf

Create or update your buf.gen.yaml:

version: v2
plugins:
  - local: protoc-gen-go
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-connect-go
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-connect-go-mcp
    out: gen
    opt: paths=source_relative

Then run:

buf generate

With protoc

protoc \
  --go_out=. --go_opt=paths=source_relative \
  --connect-go_out=. --connect-go_opt=paths=source_relative \
  --connect-go-mcp_out=. --connect-go-mcp_opt=paths=source_relative \
  your_service.proto

Configuration Options

package_suffix

Controls the package naming and directory structure for generated files.

Default Behavior (no package_suffix)

plugins:
  - local: protoc-gen-connect-go-mcp
    out: gen
    opt: paths=source_relative

Output: gen/greetv1mcp/greet.mcpserver.go with package greetv1mcp

Custom Suffix

plugins:
  - local: protoc-gen-connect-go-mcp
    out: gen
    opt: paths=source_relative,package_suffix=tools

Output: gen/greetv1tools/greet.mcpserver.go with package greetv1tools

Empty Suffix (Flat Structure)

plugins:
  - local: protoc-gen-connect-go-mcp
    out: gen
    opt: paths=source_relative,package_suffix=

Output: gen/greet.mcpserver.go with package greetv1

Example

Input Proto File

syntax = "proto3";

package greet.v1;

option go_package = "github.com/example/gen/greet/v1;greetv1";

// Greeting service for MCP demonstration
service GreetService {
  // Greet RPC
  // This method greets a user
  // Parameter name: The name of the person to greet (required)
  // Returns: A personalized greeting message
  rpc Greet(GreetRequest) returns (GreetResponse);

  // Ping RPC
  // Simple ping-pong method for testing connectivity
  rpc Ping(PingRequest) returns (PingResponse);
}

message GreetRequest {
  string name = 1; // Name of the person to greet
}

message GreetResponse {
  string message = 1; // Greeting message
}

message PingRequest {
  string message = 1; // Ping message
}

message PingResponse {
  string message = 1; // Pong response
}

Generated MCP Server

// Code generated by connect-go-mcp DO NOT EDIT.
package greetv1mcp

import (
    "context"

    "github.com/google/jsonschema-go/jsonschema"
    "github.com/modelcontextprotocol/go-sdk/mcp"
    connectgomcp "github.com/yoshihiro-shu/connect-go-mcp"
)

// NewMCPServerWithTools creates and returns a configured GreetService MCP server
func NewGreetServiceMCPServer(baseURL string, opts ...connectgomcp.ClientOption) *mcp.Server {
    server := mcp.NewServer(&mcp.Implementation{
        Name:    "GreetService",
        Version: "1.0.0",
    }, nil)

    toolHandler := connectgomcp.NewToolHandler(baseURL, opts...)

    mcp.AddTool(
        server,
        &mcp.Tool{
            Name:        "Greet",
            Description: "Greet RPC\n\nGreeting request\nThis is a test for multi-line comments\nParameter name: The name of the person to greet",
            InputSchema: &jsonschema.Schema{
                Type: "object",
                Properties: map[string]*jsonschema.Schema{
                    "name": {
                        Type:        "string",
                        Description: "name",
                    },
                },
            },
        },
        func(ctx context.Context, req *mcp.CallToolRequest, input map[string]any) (*mcp.CallToolResult, any, error) {
            result, err := toolHandler.Handle(ctx, req, "greet.v1.GreetService/Greet", input)
            if err != nil {
                return nil, nil, err
            }
            return result, nil, nil
        },
    )

    mcp.AddTool(
        server,
        &mcp.Tool{
            Name:        "Ping",
            Description: "Ping RPC\n\nPing request",
            InputSchema: &jsonschema.Schema{
                Type: "object",
                Properties: map[string]*jsonschema.Schema{
                    "message": {
                        Type:        "string",
                        Description: "message",
                    },
                },
            },
        },
        func(ctx context.Context, req *mcp.CallToolRequest, input map[string]any) (*mcp.CallToolResult, any, error) {
            result, err := toolHandler.Handle(ctx, req, "greet.v1.GreetService/Ping", input)
            if err != nil {
                return nil, nil, err
            }
            return result, nil, nil
        },
    )

    return server
}

Endpoint Path Format

The generated code uses Connect-Go's standard path format for endpoints:

{baseURL}/{package}.{Service}/{Method}

For example, with baseURL = "http://localhost:8080":

• greet.v1.GreetService/Greet → http://localhost:8080/greet.v1.GreetService/Greet

Using the Generated Server

package main

import (
    "context"
    "log"

    "github.com/modelcontextprotocol/go-sdk/mcp"
    greetv1mcp "github.com/example/gen/greet/v1/greetv1mcp"
)

func main() {
    // Create MCP server instance
    mcpServer := greetv1mcp.NewGreetServiceMCPServer("http://localhost:8080")

    // Start the MCP server with stdio transport
    ctx := context.Background()
    if err := mcpServer.Run(ctx, &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

Client Options

You can customize the HTTP client behavior using ClientOption:

import (
    "net/http"
    "time"

    connectgomcp "github.com/yoshihiro-shu/connect-go-mcp"
    greetv1mcp "github.com/example/gen/greet/v1/greetv1mcp"
)

// Custom HTTP client with timeout
customClient := &http.Client{
    Timeout: 30 * time.Second,
}

// Custom headers (e.g., for authentication)
headers := map[string]string{
    "Authorization": "Bearer your-token",
    "X-Custom-Header": "custom-value",
}

// Create server with options
mcpServer := greetv1mcp.NewGreetServiceMCPServer(
    "http://localhost:8080",
    connectgomcp.WithHTTPClient(customClient),
    connectgomcp.WithHTTPHeaders(headers),
)

Utility Functions

ListTools

Retrieve the list of registered tools from an MCP server:

import (
    "context"
    "fmt"

    connectgomcp "github.com/yoshihiro-shu/connect-go-mcp"
    greetv1mcp "github.com/example/gen/greet/v1/greetv1mcp"
)

server := greetv1mcp.NewGreetServiceMCPServer("http://localhost:8080")
tools, err := connectgomcp.ListTools(context.Background(), server)
if err != nil {
    log.Fatal(err)
}

for _, tool := range tools {
    fmt.Printf("Tool: %s - %s\n", tool.Name, tool.Description)
}

FilterTools

Filter out tools by name pattern using regular expressions:

import (
    "regexp"

    connectgomcp "github.com/yoshihiro-shu/connect-go-mcp"
    greetv1mcp "github.com/example/gen/greet/v1/greetv1mcp"
)

server := greetv1mcp.NewGreetServiceMCPServer("http://localhost:8080")

// Remove tools matching the pattern (e.g., remove all "List*" tools)
excludePattern := regexp.MustCompile(`^List`)
server = connectgomcp.FilterTools(server, excludePattern)

Generated Code Structure

The plugin generates:

1. MCP Server Constructor: New{ServiceName}MCPServer() function
2. Tool Definitions: Each RPC method becomes an MCP tool with method name (e.g., Greet)
3. InputSchema: JSON Schema for tool parameters with type definitions
4. Parameter Mapping: Proto message fields become tool parameters
5. Comments: Preserved as tool descriptions (both RPC comments and request message comments)
6. Type Safety: Full Go type safety for all operations
7. Endpoint Paths: Uses fully qualified service name format ({package}.{Service}/{Method})

InputSchema Type Mapping

Proto types are automatically mapped to JSON Schema types:

Proto Type	JSON Schema Type
string	string
bool	boolean
int32, int64	integer
float, double	number
Other types	object

Integration with MCP Ecosystem

The generated servers are compatible with:

• Claude Desktop: Add as MCP tools for AI assistance
• MCP Clients: Any client implementing the MCP protocol
• Custom Applications: Integrate MCP functionality into your apps

Development

Running Tests

cd cmd/protoc-gen-connect-go-mcp
go test -v

Test Requirements

• Protocol Buffers compiler (protoc) must be installed
• Tests automatically skip if protoc is not available

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License.

Related Projects

• go-sdk - Official MCP Go SDK
• connect-go - Simple, reliable, interoperable RPC
• buf - Protocol Buffer toolkit
• Model Context Protocol - Official MCP documentation