Connect Go MCP
No description available
Ask AI about Connect Go MCP
Powered by Claude · Grounded in docs
I know everything about Connect Go MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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-gofor 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) bufCLI 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:
- MCP Server Constructor:
New{ServiceName}MCPServer()function - Tool Definitions: Each RPC method becomes an MCP tool with method name (e.g.,
Greet) - InputSchema: JSON Schema for tool parameters with type definitions
- Parameter Mapping: Proto message fields become tool parameters
- Comments: Preserved as tool descriptions (both RPC comments and request message comments)
- Type Safety: Full Go type safety for all operations
- 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
protocis not available
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
