mcp

Documentation

Overview

Package mcp provides MCP (Model Context Protocol) integration for gains.

MCP is a protocol that enables AI assistants to access external tools and data. This package provides bidirectional integration:

• Server: Expose a gains tool.Registry as an MCP server, allowing MCP clients like Claude Desktop to discover and use your tools.
• Client: Connect to MCP servers and use their tools through RemoteRegistry, which can be used with gains agents.

Exposing Tools as an MCP Server

To expose your gains tools to MCP clients:

registry := tool.NewRegistry().Add(
    tool.Func("weather", "Get weather", weatherHandler),
    tool.Func("search", "Search web", searchHandler),
)

// Serve over stdio (for subprocess-based MCP clients)
if err := mcp.ServeStdio(registry); err != nil {
    log.Fatal(err)
}

Consuming MCP Servers

To use tools from an MCP server with a gains agent:

// Connect to an MCP server
remote, err := mcp.NewRemoteRegistry(ctx, "./my-mcp-server", nil)
if err != nil {
    log.Fatal(err)
}
defer remote.Close()

// Use the remote tools with an agent
agent := agent.New(client)
for _, t := range remote.Tools() {
    agent.RegisterTool(t, remote.Execute)
}

Index

• func FromMCPCallToolResult(callID string, result *mcp.CallToolResult) ai.ToolResult
• func FromMCPTool(t mcp.Tool) ai.Tool
• func FromMCPTools(tools []mcp.Tool) []ai.Tool
• func NewServer(registry *tool.Registry, opts ...ServerOption) *server.MCPServer
• func ServeStdio(registry *tool.Registry, opts ...ServerOption) error
• func ToMCPCallToolRequest(call ai.ToolCall) mcp.CallToolRequest
• func ToMCPCallToolResult(result ai.ToolResult) *mcp.CallToolResult
• func ToMCPTool(t ai.Tool) mcp.Tool
• func ToMCPTools(tools []ai.Tool) []mcp.Tool
• type RemoteRegistry
  • func NewRemoteRegistry(ctx context.Context, command string, env []string, args ...string) (*RemoteRegistry, error)
  • func NewRemoteRegistryFromClient(ctx context.Context, c *client.Client) (*RemoteRegistry, error)
  • func NewRemoteRegistrySSE(ctx context.Context, baseURL string) (*RemoteRegistry, error)
  • func (r *RemoteRegistry) Close() error
  • func (r *RemoteRegistry) Execute(ctx context.Context, call ai.ToolCall) (ai.ToolResult, error)
  • func (r *RemoteRegistry) GetTool(name string) (ai.Tool, bool)
  • func (r *RemoteRegistry) Has(name string) bool
  • func (r *RemoteRegistry) Len() int
  • func (r *RemoteRegistry) Names() []string
  • func (r *RemoteRegistry) Refresh(ctx context.Context) error
  • func (r *RemoteRegistry) Tools() []ai.Tool
• type ServerOption
  • func WithName(name string) ServerOption
  • func WithVersion(version string) ServerOption

Functions

func FromMCPCallToolResult

func FromMCPCallToolResult(callID string, result *mcp.CallToolResult) ai.ToolResult

FromMCPCallToolResult converts an MCP CallToolResult to a gains ToolResult. The result content is extracted and concatenated as text.

func FromMCPTool

func FromMCPTool(t mcp.Tool) ai.Tool

FromMCPTool converts an MCP Tool to a gains Tool. It extracts the JSON schema from either RawInputSchema or InputSchema.

func FromMCPTools

func FromMCPTools(tools []mcp.Tool) []ai.Tool

FromMCPTools converts a slice of MCP Tools to gains Tools.

func NewServer

func NewServer(registry *tool.Registry, opts ...ServerOption) *server.MCPServer

NewServer creates an MCP server that exposes tools from a gains tool.Registry. Each tool in the registry is registered with the MCP server, allowing MCP clients to discover and call the tools.

Example:

registry := tool.NewRegistry().Add(
    tool.Func("weather", "Get weather", weatherHandler),
    tool.Func("search", "Search web", searchHandler),
)

mcpServer := mcp.NewServer(registry,
    mcp.WithName("my-tools"),
    mcp.WithVersion("1.0.0"),
)

server.ServeStdio(mcpServer)

func ServeStdio

func ServeStdio(registry *tool.Registry, opts ...ServerOption) error

ServeStdio starts an MCP server that communicates over stdin/stdout. This is the standard transport for MCP servers invoked as subprocesses.

Example:

registry := tool.NewRegistry().Add(
    tool.Func("hello", "Say hello", helloHandler),
)

if err := mcp.ServeStdio(registry); err != nil {
    log.Fatal(err)
}

func ToMCPCallToolRequest

func ToMCPCallToolRequest(call ai.ToolCall) mcp.CallToolRequest

ToMCPCallToolRequest converts a gains ToolCall to an MCP CallToolRequest.

func ToMCPCallToolResult

func ToMCPCallToolResult(result ai.ToolResult) *mcp.CallToolResult

ToMCPCallToolResult converts a gains ToolResult to an MCP CallToolResult.

func ToMCPTool

func ToMCPTool(t ai.Tool) mcp.Tool

ToMCPTool converts a gains Tool to an MCP Tool. The gains Tool.Parameters JSON schema is used as the MCP Tool's RawInputSchema.

func ToMCPTools

func ToMCPTools(tools []ai.Tool) []mcp.Tool

ToMCPTools converts a slice of gains Tools to MCP Tools.

Types

type RemoteRegistry

type RemoteRegistry struct {
	// contains filtered or unexported fields
}

RemoteRegistry provides access to tools from an MCP server. It implements a similar interface to tool.Registry but proxies tool calls to the remote MCP server.

RemoteRegistry is safe for concurrent use. The tool list is cached locally and can be refreshed with RemoteRegistry.Refresh.

func NewRemoteRegistry

func NewRemoteRegistry(ctx context.Context, command string, env []string, args ...string) (*RemoteRegistry, error)

NewRemoteRegistry creates a RemoteRegistry connected to an MCP server via stdio. The command is the path to the MCP server executable, and args are passed to it.

Example:

registry, err := mcp.NewRemoteRegistry(ctx, "./my-mcp-server", nil)
if err != nil {
    log.Fatal(err)
}
defer registry.Close()

// Use with an agent
agent := agent.New(client, agent.WithToolRegistry(registry))

func NewRemoteRegistryFromClient

func NewRemoteRegistryFromClient(ctx context.Context, c *client.Client) (*RemoteRegistry, error)

NewRemoteRegistryFromClient creates a RemoteRegistry from an existing MCP client. The client must already be started. This function will initialize it and fetch tools.

func NewRemoteRegistrySSE

func NewRemoteRegistrySSE(ctx context.Context, baseURL string) (*RemoteRegistry, error)

NewRemoteRegistrySSE creates a RemoteRegistry connected to an MCP server via SSE.

Example:

registry, err := mcp.NewRemoteRegistrySSE(ctx, "http://localhost:8080/mcp")
if err != nil {
    log.Fatal(err)
}
defer registry.Close()

func (*RemoteRegistry) Close

func (r *RemoteRegistry) Close() error

Close closes the connection to the MCP server.

func (*RemoteRegistry) Execute

func (r *RemoteRegistry) Execute(ctx context.Context, call ai.ToolCall) (ai.ToolResult, error)

Execute calls a tool on the remote MCP server.

func (*RemoteRegistry) GetTool

func (r *RemoteRegistry) GetTool(name string) (ai.Tool, bool)

GetTool retrieves a tool definition by name.

func (*RemoteRegistry) Has

func (r *RemoteRegistry) Has(name string) bool

Has returns true if the registry has a tool with the given name.

func (*RemoteRegistry) Len

func (r *RemoteRegistry) Len() int

Len returns the number of available tools.

func (*RemoteRegistry) Names

func (r *RemoteRegistry) Names() []string

Names returns the names of all available tools.

func (*RemoteRegistry) Refresh

func (r *RemoteRegistry) Refresh(ctx context.Context) error

Refresh fetches the current list of tools from the MCP server. This can be called to update the tool list if the server's tools change.

func (*RemoteRegistry) Tools

func (r *RemoteRegistry) Tools() []ai.Tool

Tools returns all tools available from the MCP server.

type ServerOption

type ServerOption func(*serverConfig)

ServerOption configures a Server.

func WithName

func WithName(name string) ServerOption

WithName sets the server name reported to MCP clients.

func WithVersion

func WithVersion(version string) ServerOption

WithVersion sets the server version reported to MCP clients.