mcp

Documentation

Overview

Package mcp is a zero-dependency Model Context Protocol client that surfaces remote tools as first-class tool.Tool values. It is client-only: it can launch stdio servers and talk to Streamable HTTP servers, but it never exposes a service of its own.

From the model's point of view an MCP tool is indistinguishable from a local one — it is still function calling; only the execution boundary moved:

c, err := mcp.Dial(ctx, mcp.Stdio("npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"))
defer c.Close()

tools, err := c.Tools(ctx)          // []tool.Tool proxying tools/call
set := tool.NewSet(tools...)        // ...or box.Namespace("fs", ..., toolbox.Tools(tools...))

Index

• Constants
• type Client
  • func Dial(ctx context.Context, ep Endpoint, opts ...Option) (*Client, error)
  • func (c *Client) Call(ctx context.Context, name string, args json.RawMessage) (*tool.Result, error)
  • func (c *Client) Close() error
  • func (c *Client) Instructions() string
  • func (c *Client) ListTools(ctx context.Context) ([]ToolInfo, error)
  • func (c *Client) NegotiatedVersion() string
  • func (c *Client) ServerInfo() Info
  • func (c *Client) ToolSet(ctx context.Context) (*tool.Set, error)
  • func (c *Client) Tools(ctx context.Context) ([]tool.Tool, error)
• type Endpoint
• type HTTPEndpoint
  • func HTTP(url string) *HTTPEndpoint
• type Info
• type Option
  • func WithClientInfo(info Info) Option
  • func WithToolPrefix(prefix string) Option
• type RPCError
  • func (e *RPCError) Error() string
• type StdioEndpoint
  • func Stdio(command string, args ...string) *StdioEndpoint
• type ToolInfo

Constants

const ProtocolVersion = "2025-06-18"

ProtocolVersion is the MCP revision this client speaks by default. The server may negotiate down during initialize; Client.NegotiatedVersion reports the result.

Types

type Client

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

Client is a live, initialized connection to one MCP server. It is safe for concurrent use.

func Dial

func Dial(ctx context.Context, ep Endpoint, opts ...Option) (*Client, error)

Dial connects to the endpoint and runs the MCP initialize handshake.

func (*Client) Call

func (c *Client) Call(ctx context.Context, name string, args json.RawMessage) (*tool.Result, error)

Call invokes one remote tool by its wire name (no prefix) and folds the MCP result into a tool.Result: text content blocks are concatenated, non-text blocks are annotated, and structuredContent is appended as JSON when there is no text at all.

func (*Client) Close

func (c *Client) Close() error

Close tears the connection down (and, for stdio, the child process).

func (*Client) Instructions

func (c *Client) Instructions() string

Instructions returns the server-provided usage guidance from initialize, if any — a natural fit for a toolbox namespace's Instructions.

func (*Client) ListTools

func (c *Client) ListTools(ctx context.Context) ([]ToolInfo, error)

ListTools fetches the server's tool catalogue (following pagination).

func (*Client) NegotiatedVersion

func (c *Client) NegotiatedVersion() string

NegotiatedVersion reports the protocol version agreed at initialize.

func (*Client) ServerInfo

func (c *Client) ServerInfo() Info

ServerInfo reports the server's identity from the handshake.

func (*Client) ToolSet

func (c *Client) ToolSet(ctx context.Context) (*tool.Set, error)

ToolSet is Tools folded into a ready-to-use *tool.Set.

func (*Client) Tools

func (c *Client) Tools(ctx context.Context) ([]tool.Tool, error)

Tools lists the server's tools and wraps each as a tool.Tool whose Invoke proxies tools/call over this connection. The tools stay bound to the Client; close it and they stop working.

type Endpoint

type Endpoint interface {
	// contains filtered or unexported methods
}

Endpoint describes where and how to reach an MCP server. Stdio and HTTP are the two provided constructors.

type HTTPEndpoint

type HTTPEndpoint struct {
	URL string
	// Header is attached to every request — the place for Authorization.
	Header http.Header
	// Client is the http.Client to use (nil = http.DefaultClient).
	Client *http.Client
}

HTTPEndpoint connects to a remote MCP server over the Streamable HTTP transport (client side only — Arcus never exposes an HTTP service). Build one with HTTP, optionally set Header/Client, then hand it to Dial.

func HTTP

func HTTP(url string) *HTTPEndpoint

HTTP describes a remote MCP server:

ep := mcp.HTTP("https://example.com/mcp")
ep.Header = http.Header{"Authorization": {"Bearer " + token}}
c, err := mcp.Dial(ctx, ep)

type Info

type Info struct {
	Name    string `json:"name"`
	Title   string `json:"title,omitempty"`
	Version string `json:"version"`
}

Info identifies an MCP implementation (client or server).

type Option

type Option func(*Client)

Option configures Dial.

func WithClientInfo

func WithClientInfo(info Info) Option

WithClientInfo overrides the client identity sent during initialize.

func WithToolPrefix

func WithToolPrefix(prefix string) Option

WithToolPrefix prefixes every proxied tool's advertised name, so tools from several servers can coexist in one set without clashing:

mcp.Dial(ctx, ep, mcp.WithToolPrefix("fs_"))   // read_file -> fs_read_file

The prefix is stripped again before the call goes over the wire.

type RPCError

type RPCError struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

RPCError is a JSON-RPC error object returned by the server.

func (*RPCError) Error

func (e *RPCError) Error() string

type StdioEndpoint

type StdioEndpoint struct {
	Command string
	Args    []string
	// Dir is the child's working directory ("" = inherit).
	Dir string
	// Env is the child's environment (nil = inherit the parent's).
	Env []string
	// Stderr receives the child's stderr (nil = the parent's stderr), which is
	// where MCP servers put their logs.
	Stderr io.Writer
}

StdioEndpoint launches an MCP server as a child process and speaks newline-delimited JSON-RPC over its stdin/stdout (the MCP stdio transport). Build one with Stdio, optionally set Dir/Env, then hand it to Dial.

func Stdio

func Stdio(command string, args ...string) *StdioEndpoint

Stdio describes a subprocess MCP server:

c, err := mcp.Dial(ctx, mcp.Stdio("npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"))

type ToolInfo

type ToolInfo struct {
	Name        string          `json:"name"`
	Title       string          `json:"title,omitempty"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"inputSchema,omitempty"`
}

ToolInfo is a tool as advertised by the server via tools/list.