GoMCP

GoMCP - Go Model Context Protocol Library

✅ Full compliance across all MCP specification versions- SeeCOMPLIANCE.mdfor detailed verification.

- Overview
- Key Features
- API Stability
- Installation
- Quickstart

- Client Example
- Client with Automatic Server Management
- Server Example
- Advanced Server Example

- Clients and Servers
- Tools
- Resources
- Prompts
- Batch Operations
- Event System
- Transports
- Server Management
- Session Management

package main import ( "log" "github.com/localrivet/gomcp/client" ) func main() { // Create a new client with stdio transport c, err := client.NewClient("stdio:///", client.WithStdio(), client.WithProtocolVersion("2025-03-26"), client.WithProtocolNegotiation(true), ) if err != nil { log.Fatalf("Failed to create client: %v", err) } defer c.Close() // Call a tool on the MCP server result, err := c.CallTool("say_hello", map[string]interface{}{ "name": "World", }) if err != nil { log.Fatalf("Tool call failed: %v", err) } log.Printf("Result: %v", result) }

Note: This example uses stdio transport, which means the client expects to communicate with an MCP server via stdin/stdout. For a complete working example that automatically manages the server process, see the "Client with Automatic Server Management" section below.

What this does:This example demonstrates GoMCP's powerful automatic server management feature. Instead of manually starting and stopping MCP server processes, the client can automatically:

- Launch server processeson demand using system commands
- Establish connectionsto those servers via stdio/pipes
- Environment variable injectionfor configuration (API keys, etc.)
- Automatic cleanup- server processes are terminated when the client closes
- Process lifecycle management- handles server startup, health checks, and shutdown

Why this matters:This pattern eliminates the operational complexity of managing MCP servers. You can distribute a single binary that automatically spins up the required MCP servers, making deployment and integration much simpler. It's especially useful for:

- Development environments- automatically start dependent services
- CI/CD pipelines- spin up servers for testing without manual setup
- Desktop applications- embed MCP servers without requiring separate installation
- Microservice architectures- manage server dependencies declaratively

package main import ( "log" "github.com/localrivet/gomcp/client" ) func main() { // Define server configuration config := client.ServerConfig{ MCPServers: map[string]client.ServerDefinition{ "govibe": { Command: "govibe", Args: []string{}, Env: map[string]string{ "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}", }, }, }, } // Create a client with automatic server management c, err := client.NewClient("my-client", client.WithServers(config, "govibe"), ) if err != nil { log.Fatalf("Failed to create client: %v", err) } defer c.Close() // Automatically stops the server process // Call a tool on the managed server result, err := c.CallTool("add_task", map[string]interface{}{ "prompt": "Create a login page with authentication", }) if err != nil { log.Fatalf("Tool call failed: %v", err) } log.Printf("Task created: %v", result) // Add project roots for the server to access err = c.AddRoot("/path/to/project", "project-root") if err != nil { log.Fatalf("Failed to add root: %v", err) } // Get a resource that might use the project context resource, err := c.GetResource("/project/files/src/main.go") if err != nil { log.Fatalf("Resource request failed: %v", err) } log.Printf("Resource content: %v", resource) }

- The${ANTHROPIC_API_KEY}syntax automatically injects environment variables from the current process
- Server processes communicate viastdio pipesfor secure, high-performance IPC
- The client waits for server initialization before accepting requests
- Graceful shutdownensures servers are properly terminated, preventing orphaned processes
- Multiple servers can be managed simultaneously with different configurations

package main import ( "fmt" "log/slog" "os" "github.com/localrivet/gomcp/server" ) func main() { // Create a logger logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ Level: slog.LevelInfo, })) // Create a new server srv := server.NewServer("example-server", server.WithLogger(logger), ).AsStdio() // Register a tool with inline struct srv.Tool("say_hello", "Greet someone", func(ctx server.Context, args struct { Name string json:"name" }) (interface{}, error) { return map[string]interface{}{ "message": fmt.Sprintf("Hello, %s!", args.Name), }, nil }) // Start the server if err := srv.Run(); err != nil { log.Fatalf("Failed to run server: %v", err) } }

package main import ( "fmt" "log/slog" "os" "path/filepath" "strings" "github.com/localrivet/gomcp/server" "github.com/localrivet/gomcp/transport/sse" ) func main() { // Create a logger logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ Level: slog.LevelInfo, })) // Create a new server with comprehensive functionality srv := server.NewServer("advanced-server", server.WithLogger(logger), ).AsStdio() // Register multiple tools with different parameter types srv.Tool("calculator", "Perform mathematical calculations", func(ctx server.Context, args struct { Operation string json:"operation" A float64 json:"a" B float64 json:"b" }) (interface{}, error) { switch args.Operation { case "add": return map[string]interface{}{"result": args.A + args.B}, nil case "multiply": return map[string]interface{}{"result": args.A  args.B}, nil case "divide": if args.B == 0 { return nil, fmt.Errorf("division by zero") } return map[string]interface{}{"result": args.A / args.B}, nil default: return nil, fmt.Errorf("unsupported operation: %s", args.Operation) } }) srv.Tool("create_file", "Create a file with content", func(ctx server.Context, args struct { Path string json:"path" Content string json:"content" }) (interface{}, error) { // In a real implementation, you'd validate paths and permissions return map[string]interface{}{ "message": fmt.Sprintf("File created at %s with %d bytes", args.Path, len(args.Content)), "path": args.Path, "size": len(args.Content), }, nil }) // Register resources with different patterns srv.Resource("/config", "Get server configuration", func(ctx server.Context, args struct{}) (interface{}, error) { return map[string]interface{}{ "version": "1.0.0", "environment": "development", "features": []string{"tools", "resources", "prompts"}, }, nil }) // Templated resource for file access srv.Resource("/files/{path}", "Access file system resources", func(ctx server.Context, args struct { Path string path:"path" }) (interface{}, error) { // Extract file extension for content type detection ext := strings.ToLower(filepath.Ext(args.Path)) return map[string]interface{}{ "path": args.Path, "extension": ext, "type": getFileType(ext), "content": fmt.Sprintf("Mock content for file: %s", args.Path), }, nil }) // User profile resource with parameters srv.Resource("/users/{id}", "Get user profile information", func(ctx server.Context, args struct { ID string path:"id" IncludePosts bool json:"include_posts" }) (interface{}, error) { user := map[string]interface{}{ "id": args.ID, "name": fmt.Sprintf("User %s", args.ID), "email": fmt.Sprintf("user%s@example.com", args.ID), "active": true, } if args.IncludePosts { user["posts"] = []map[string]interface{}{ {"id": 1, "title": "Hello World", "content": "First post"}, {"id": 2, "title": "Second Post", "content": "Another post"}, } } return user, nil }) // Register prompts for different use cases srv.Prompt("code_review", "Provide code review assistance", server.User("Please review this {{language}} code for best practices, potential bugs, and improvements:\n\n

- client.Client: Interface for communicating with MCP servers. Handles protocol negotiation, request/response management, and server lifecycle.
- server.Server: Core component for implementing MCP servers. Provides registration methods for tools, resources, and prompts with automatic schema generation.
Tools expose functions that LLMs can call to perform actions. GoMCP supports:
- Type-safe parametersusing inline struct definitions

- Automatic schema generationfrom Go struct tags

- Error handlingwith proper MCP error responses

- Cancellation supportfor long-running operations

Resources provide structured data to LLMs in various formats:

- Static resourceswith fixed URIs (e.g.,/config,/status)

- Templated resourceswith path parameters (e.g.,/files/{path},/users/{id})

- Dynamic resourcesthat can accept additional parameters from request bodies

- Multiple content typesincluding text, images, links, and binary data

Prompts define reusable message templates for LLM interactions:

- Template variablesusing{{variable}}syntax

- Multiple message types(User, Assistant, System)

- Role-based conversationsfor complex interaction patterns

- Argument validationfor template parameters

GoMCP supports JSON-RPC batch operations for improved performance:

- Reduced network round-tripsby sending multiple requests at once

- Maintained request orderingin responses

- Mixed request types(tools, resources, prompts) in a single batch

- Partial failure handlingwith individual response errors

- Fluent builder interfacefor easy batch construction

GoMCP provides a comprehensive event system that allows you to monitor and react to various activities within your MCP server or client. The event system uses a type-safe, channel-based architecture for maximum performance and reliability.

- Real-time monitoringof server operations and client interactions

- Type-safe event handlingwith strongly-typed event structs

- Channel-based architecturefor high-performance, non-blocking event processing

- Comprehensive coverageof all server lifecycle and operation events

- Easy integrationwith logging, metrics, and monitoring systems
GoMCP emits events for all major operations and lifecycle changes:
- server.initialized- Server has started and is ready to accept requests

- server.shutdown- Server is shutting down
- client.connected- A client connected to the server

- client.disconnected- A client disconnected from the server

- client.initializing- Client is starting to connect (client-side)

- client.initialized- Client successfully connected (client-side)

- client.error- Client operation failed (client-side)
- tool.registered- A tool was registered with the server

- resource.registered- A resource was registered with the server
- tool.executed- A tool was executed (successful operation)

- resource.accessed- A resource was accessed

- prompt.executed- A prompt was executed

- request.failed- Any MCP request failed
All events include comprehensive metadata and follow consistent patterns:
Server Eventsinclude server name, timestamps, and operational metricsClient Eventsinclude session IDs, protocol versions, and connection details

Operation Eventsinclude method names, actual JSON payloads, and execution resultsError Eventsinclude detailed error information and context for debugging
For a complete working example with all event types, seeexamples/events_integration/main.go.

GoMCP supports multiple transport layers for different use cases:

Note on SSE Transport:The SSE transport correctly implements the MCP "Streamable HTTP" specification (2025-03-26):

- Single MCP Endpoint: Uses one endpoint that handles both GET (for SSE) and POST (for messages)

- Client Requests: Sent via HTTP POST to the MCP endpoint

- Server Responses: Can be immediate JSON responses or SSE streams

- Server-Initiated Messages: Sent via GET-initiated SSE streams

- Session Management: Optional session IDs viaMcp-Session-Idheader

- Backward Compatibility: Supports legacy 2024-11-05 pattern with automatic fallback

GoMCP provides automatic management of external MCP server processes:
- Automatic process startupfrom configuration files or programmatic definitions

- Environment variable injectionwith${VAR}syntax

- Graceful shutdownand cleanup when clients disconnect

- Multi-server supportfor complex architectures

- Health monitoringand connection management

Configuration File Example (mcp-servers.json):

When using server registries with multiple MCP servers, it's important to follow proper cleanup patterns to avoid race conditions:

✅ Correct Pattern: Use registry.StopAll()

❌ Incorrect Pattern: Manual client.Close() before registry.StopAll()

- client.Close()immediately terminates the MCP connection and may kill the server process

- registry.StopAll()then tries to gracefully shut down processes that are already dead

- This results in "Failed to wait for server process error='signal: killed'" errors

- Always useregistry.StopAll()- it handles all client cleanup internally

- Use defer blocksfor guaranteed cleanup on program exit

- Don't mix manual client.Close() with registry.StopAll()

- Handle cleanup errors gracefully- processes may have already exited
GoMCP v1.5.5 introduces comprehensive session management with the MCP Session Architecture, providing rich context and automated workspace discovery:

GoMCP automatically extracts session data from the transport layer per MCP specification:

- stdio: Environment from process environment variables

- HTTP: Environment from request headers (X-Env-pattern)

- WebSocket: Environment from connection headers

- SSE: Environment from initial request headers

The server automatically detects when clients support therootscapability and:

- Initial Extraction: Extracts workspace roots fromclientInfo.rootsduring initialization

- Capability Detection: Detects if client advertisesrootscapability

- Automated Fetching: Sendsroots/listrequests afternotifications/initialized

- Response Handling: Processesroots/listresponses with proper request tracking

- Context Integration: Makes roots available viactx.Session.Roots()
Full compliance across all three MCP protocol versions:
- 2024-11-05: Basic root extraction and capability detection

- 2025-03-26: Enhanced session management with audio support detection

- draft: Latest features with full session architecture
EnhancedClientInfoprovides comprehensive session data: