gomcp

GoMCP is a complete Go implementation of the Model Context Protocol (MCP). It provides an idiomatic Go API for both clients and servers and supports multiple transports (including stdio, HTTP, WebSocket, and Server-Sent Events) with automatic version negotiation across MCP specification versions. This repository/documentation focuses on the gomcp library, which enables you to create MCP clients and, with the accompanying examples, automatically manage external MCP server processes. You can use the client API to call tools, fetch resources, prompt rendering, and manage sessions, while the server management features allow you to launch and manage external MCP servers on-demand in your application. The library emphasizes a type-safe API, stable interfaces, and a clear path to production deployments.

To get started, create a client that uses the stdio transport to communicate with an MCP server, or leverage the automatic server management to spin up server processes on demand. The client exposes methods such as CallTool, GetResource, GetPrompt, and more, enabling tool calls and structured data exchange with LLMs through the MCP protocol. The gomcp ecosystem also includes facilities for session management, transport adapters, and a robust event system, making it suitable for complex workflows that require real-time updates and server orchestration.

For typical usage, initialize a client with the desired transport (e.g., stdio) and protocol version, then perform tool calls or resource retrieval. If you need to run dependent MCP servers automatically, configure the ServerConfig with the definitions (command, args, and environment) and let the client manage lifecycle, health checks, and cleanup. This approach reduces operational overhead and simplifies integration in development, CI, and desktop applications.

Prerequisites:

• Go (1.18+ recommended)
• Basic Go workspace setup (GOPATH, modules enabled)

Installation steps:

1. Ensure Go is installed and your environment is configured.
2. Install the gomcp module (as a library) from GitHub: go get github.com/localrivet/gomcp
3. Optionally set up a sample server binary or script that can be launched by gomcp as part of automatic server management. If you intend to run a local server executable, ensure it is on your PATH or provide an absolute path in the ServerConfig.
4. Build and run a minimal example to verify the setup. For example, create a small Go program that imports gomcp and uses the stdio transport, then run it.

Example snippet to validate installation (paste into a .go file): package main import ( "log" "github.com/localrivet/gomcp/client" ) func main() { c, err := client.NewClient("stdio:///", client.WithStdio()) if err != nil { log.Fatalf("failed to create client: %v", err) } defer c.Close() // Example: call a tool when a server is available // result, err := c.CallTool("example_tool", map[string]interface{}{"arg": 1}) // handle result and error... }

Notes and tips:

• The library supports automatic server management, which can start external MCP servers on demand. Provide the server definitions (command, args, and environment variables) in ServerConfig to enable this feature.
• When using stdio transport, your MCP server must be compatible with stdio-based MCP communication.
• Ensure you manage environment variables securely when injecting keys or credentials into child processes.
• If you encounter protocol negotiation issues, verify that both client and server support the same MCP specification versions (e.g., 2025-03-26, 2024-11-05, or draft).
• For production deployments, prefer stable server definitions and explicit health checks within your server management logic to ensure robustness during restarts and updates.