mcp

Documentation

Overview

Package mcp implements a client for the Model Context Protocol. It supports connecting to MCP servers via stdio (subprocess) transport, discovering tools, and invoking them on behalf of the primary model.

Index

• func TestConnection(ctx context.Context, cfg config.MCPServerConfig) (int, error)
• type MCPClient
  • func NewMCPClient(configs []config.MCPServerConfig, debug bool) *MCPClient
  • func (c *MCPClient) CallCount() int64
  • func (c *MCPClient) CallTool(ctx context.Context, serverName, toolName string, args json.RawMessage) (string, error)
  • func (c *MCPClient) Close() error
  • func (c *MCPClient) Connect(ctx context.Context) error
  • func (c *MCPClient) DisconnectServer(serverName string)
  • func (c *MCPClient) IsServerReadOnly(serverName string) bool
  • func (c *MCPClient) Prompts() []MCPPrompt
  • func (c *MCPClient) ReadOnlyToolDefinitions() []provider.ToolDefinition
  • func (c *MCPClient) Reconfigure(ctx context.Context, newConfigs []config.MCPServerConfig) error
  • func (c *MCPClient) Reconnect(ctx context.Context, serverName string) error
  • func (c *MCPClient) ResolveToolCall(prefixedName string) (serverName, toolName string, ok bool)
  • func (c *MCPClient) Resources() []MCPResource
  • func (c *MCPClient) SetNotificationHandler(handler func(serverName, method string, params json.RawMessage))
  • func (c *MCPClient) Status() []ServerStatus
  • func (c *MCPClient) ToToolDefinitions() []provider.ToolDefinition
  • func (c *MCPClient) Tools() []MCPTool
• type MCPPrompt
• type MCPPromptArgument
• type MCPResource
• type MCPTool
• type ServerStatus

Functions

func TestConnection

func TestConnection(ctx context.Context, cfg config.MCPServerConfig) (int, error)

TestConnection creates a temporary connection to an MCP server using the given config, performs the initialize handshake, discovers tools, and tears down the connection. Returns the tool count or an error. Does not modify any MCPClient state — safe to call from the wizard with staged config.

Types

type MCPClient

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

MCPClient manages connections to one or more MCP servers.

func NewMCPClient

func NewMCPClient(configs []config.MCPServerConfig, debug bool) *MCPClient

NewMCPClient creates a new MCP client from the given server configurations. No connections are made until Connect is called.

func (*MCPClient) CallCount

func (c *MCPClient) CallCount() int64

CallCount returns the total number of MCP tool calls made.

func (*MCPClient) CallTool

func (c *MCPClient) CallTool(ctx context.Context, serverName, toolName string, args json.RawMessage) (string, error)

CallTool invokes a tool on the specified MCP server and returns the text result. A per-call timeout is applied from the server's Timeout config (default 30s). If the server process has died, a reconnect is attempted automatically.

func (*MCPClient) Close

func (c *MCPClient) Close() error

Close shuts down all MCP server connections.

func (*MCPClient) Connect

func (c *MCPClient) Connect(ctx context.Context) error

Connect starts all configured MCP servers and discovers their tools. Individual server failures are isolated — other servers continue to work. Returns a non-nil error summarizing any failures, but the client remains usable for servers that connected successfully.

func (*MCPClient) DisconnectServer

func (c *MCPClient) DisconnectServer(serverName string)

DisconnectServer removes and closes a single server connection and all its metadata.

func (*MCPClient) IsServerReadOnly

func (c *MCPClient) IsServerReadOnly(serverName string) bool

IsServerReadOnly returns true if the named server is configured as read-only.

func (*MCPClient) Prompts

func (c *MCPClient) Prompts() []MCPPrompt

Prompts returns all prompts discovered from connected MCP servers.

func (*MCPClient) ReadOnlyToolDefinitions

func (c *MCPClient) ReadOnlyToolDefinitions() []provider.ToolDefinition

ReadOnlyToolDefinitions returns tool definitions for MCP tools that are marked as read-only (via server config or tool annotation). These are safe to include in fan-out queries to non-primary providers.

func (*MCPClient) Reconfigure

func (c *MCPClient) Reconfigure(ctx context.Context, newConfigs []config.MCPServerConfig) error

Reconfigure diffs the current config against newConfigs and applies changes: - New servers are connected - Removed servers are disconnected - Changed servers are reconnected Updates c.configs so Status() and Reconnect() use the new set.

func (*MCPClient) Reconnect

func (c *MCPClient) Reconnect(ctx context.Context, serverName string) error

Reconnect forces a reconnection to a specific server by name. Works for both currently-connected and initially-failed servers.

func (*MCPClient) ResolveToolCall

func (c *MCPClient) ResolveToolCall(prefixedName string) (serverName, toolName string, ok bool)

ResolveToolCall takes a prefixed tool name (e.g. "mcp_filesystem_read_file") and returns the (serverName, toolName) pair via the lookup map built during tool discovery. This avoids ambiguous underscore-based string parsing.

func (*MCPClient) Resources

func (c *MCPClient) Resources() []MCPResource

Resources returns all resources discovered from connected MCP servers.

func (*MCPClient) SetNotificationHandler

func (c *MCPClient) SetNotificationHandler(handler func(serverName, method string, params json.RawMessage))

SetNotificationHandler sets a callback that is invoked when any MCP server sends a notification. This is used to handle notifications/tools/list_changed. Must be called before Connect().

func (*MCPClient) Status

func (c *MCPClient) Status() []ServerStatus

Status returns the connection status of all configured MCP servers.

func (*MCPClient) ToToolDefinitions

func (c *MCPClient) ToToolDefinitions() []provider.ToolDefinition

ToToolDefinitions converts discovered MCP tools to provider.ToolDefinition format so they can be sent to the primary model alongside built-in tools. Tool names are prefixed with "mcp_{serverName}_" to avoid collisions.

func (*MCPClient) Tools

func (c *MCPClient) Tools() []MCPTool

Tools returns all tools discovered from connected MCP servers.

type MCPPrompt

type MCPPrompt struct {
	Name        string
	Description string
	Arguments   []MCPPromptArgument
	ServerName  string
}

MCPPrompt represents a prompt template exposed by an MCP server.

type MCPPromptArgument

type MCPPromptArgument struct {
	Name        string
	Description string
	Required    bool
}

MCPPromptArgument describes an argument for a prompt template.

type MCPResource

type MCPResource struct {
	URI         string
	Name        string
	Description string
	MimeType    string
	ServerName  string
}

MCPResource represents a resource exposed by an MCP server.

type MCPTool

type MCPTool struct {
	Name        string
	Description string
	InputSchema map[string]any
	ServerName  string // which server provides this tool
	ReadOnly    bool   // true if server or tool annotation marks it read-only
}

MCPTool represents a tool discovered from an MCP server.

type ServerStatus

type ServerStatus struct {
	Name      string
	Connected bool
	Error     error
	ToolCount int
}

ServerStatus reports the connection status of a single MCP server.