Documentation
¶
Overview ¶
Package mcptools adapts a Model Context Protocol server's tools into agent.Tool. Our agent is the MCP client/host; an MCP server is a runtime source of tools whose schemas are only known at connect time (the untyped json.RawMessage path, not a Go struct). Tools() lists a connected session's tools and wraps each one so the agent core can call it like any native tool. Built on the official SDK, github.com/modelcontextprotocol/go-sdk.
Safety: by default every MCP tool is treated as a side effect (the zero agent.Safety), so it runs at most once and halts the run on an unknown-outcome resume rather than risk firing twice. MCP tool annotations are hints, and the spec says to treat them as untrusted unless they come from a trusted server: a server that labels a destructive tool read-only would otherwise have it re-run on resume, retried, and cached. For a server you trust, pass TrustAnnotations to Tools and the hints map onto agent.Safety: readOnlyHint is always safe to re-run after a crash, and idempotentHint is safe to retry.
Each tool describes itself with an agent.ToolSpec (see tool.Spec): the server's name, title, description, input schema and output schema, the Safety above, the approval gate WithApproval sets, and the per-call timeout WithCallTimeout sets.
Connect optionally wires three more client capabilities (see Option): an elicitation resolver (WithElicitation) the server can call to request structured input mid-tool-call; a tools-list-changed callback (WithToolListChanged) so a long-lived host can re-list when the server's tool set changes; and client identification (WithClientInfo). Tools() paginates the server's tool list in full (following the opaque cursor), so a server that returns its tools across several pages is never silently truncated.
The resolver also answers elicitation embedded in a tool's multi-round-trip input requests (SEP-2322), since the SDK routes those to the same handler.
Durability boundary: the resolver answers elicitation live, within the interaction that requested it; it is not a durable, resume-across-crash pause. Durability is inherited at the tool-call boundary (a tool trusted as read-only or idempotent re-runs, and so re-elicits, on resume, while any other tool halts on an unknown-outcome resume). For input that must survive a crash and resume in a fresh process, use the native agent.Interrupt in a native tool.
Index ¶
- Constants
- Variables
- func Connect(ctx context.Context, transport mcp.Transport, opts ...Option) (*mcp.ClientSession, error)
- func DeclineElicitation(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
- func Tools(ctx context.Context, session *mcp.ClientSession, opts ...ToolsOption) ([]agent.Tool, error)
- type ElicitFunc
- type Option
- type ToolsOption
- func TrustAnnotations() ToolsOption
- func WithApproval(name string, p *agent.ApprovalPolicy) ToolsOption
- func WithCallTimeout(d time.Duration) ToolsOption
- func WithMaxDescriptionBytes(n int) ToolsOption
- func WithMaxResultBytes(n int) ToolsOption
- func WithSafety(name string, s agent.Safety) ToolsOption
Constants ¶
const DefaultMaxDescriptionBytes = 8 << 10
DefaultMaxDescriptionBytes is the longest tool description, in bytes, that Tools accepts unless WithMaxDescriptionBytes says otherwise: 8 KiB. A description is sent to the model with every request, for every tool, so its size is paid on every turn of every run, and a long one is room for instructions aimed at the model. Descriptions written for a model to read are a few sentences to a page; 8 KiB (about 2,000 tokens) leaves room for a detailed one.
const DefaultMaxResultBytes = 1 << 20
DefaultMaxResultBytes is the largest tool result, in bytes of JSON, that Call accepts unless WithMaxResultBytes says otherwise: 1 MiB. A result is journaled and sent back to the model on every later turn of the run. 1 MiB of text is about 250,000 tokens, more than most models' whole context window, so a larger result cannot be used as it is; refusing it keeps one server from filling the journal and every later request.
Variables ¶
var ErrResultTooLarge = fmt.Errorf("mcp: tool result too large: %w", agent.ErrTool)
ErrResultTooLarge is a tool call whose result was larger than the limit (see WithMaxResultBytes). The tool ran; only its result was refused. It wraps agent.ErrTool.
Functions ¶
func Connect ¶
func Connect(ctx context.Context, transport mcp.Transport, opts ...Option) (*mcp.ClientSession, error)
Connect is a convenience over the SDK's client + transport: it builds a client and opens a session on the given transport (stdio, in-memory, streamable HTTP, ...). Options wire optional client capabilities (elicitation, tools-list-changed, client identity). Callers who already hold a *mcp.ClientSession can skip this and pass it to Tools.
func DeclineElicitation ¶
func DeclineElicitation(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
DeclineElicitation is a safe default resolver that declines every elicitation. Use it when the host has no way to gather the requested input.
func Tools ¶
func Tools(ctx context.Context, session *mcp.ClientSession, opts ...ToolsOption) ([]agent.Tool, error)
Tools lists the tools exposed by a connected MCP client session and returns each one wrapped as an agent.Tool. The session must already be connected (see Connect). The returned tools call back through the session, so keep it open for their lifetime. Each tool is a side effect unless TrustAnnotations is passed (see the package doc).
The server's tool list is untrusted input. Tools refuses the whole list, with an error wrapping agent.ErrProtocol, if a tool's name is outside the MCP grammar (1 to 128 of A-Z a-z 0-9 _ - .), two tools share a name, a tool's input schema is not an object schema, its output schema is present and not an object schema, or a tool's description is longer than the limit (DefaultMaxDescriptionBytes unless set with WithMaxDescriptionBytes).
Types ¶
type ElicitFunc ¶
type ElicitFunc func(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
ElicitFunc answers an MCP server's elicitation/create request: the server asks the host for structured input (a message plus a JSON schema), either as a standalone request or embedded in a tool's multi-round-trip input requests. Return an *mcp.ElicitResult with Action "accept" (and Content matching the requested schema), "decline", or "cancel". See the package doc for the durability boundary: the resolver answers live, it is not a durable pause.
type Option ¶
type Option func(*config)
Option configures the MCP client that Connect builds.
func WithClientInfo ¶
WithClientInfo overrides the client name and version reported to the server (default "bide"/"0.1.0").
func WithElicitation ¶
func WithElicitation(f ElicitFunc) Option
WithElicitation registers a resolver for the server's elicitation/create requests. Setting it advertises the elicitation capability to the server.
func WithToolListChanged ¶
WithToolListChanged registers a callback fired when the server notifies that its tool list changed. The host should re-call Tools on the session to pick up the new set: the agent core takes a fixed tool set per run, so a changed set applies to the next run the host builds, not to one already in flight.
type ToolsOption ¶
type ToolsOption func(*toolsConfig)
ToolsOption configures Tools.
func TrustAnnotations ¶
func TrustAnnotations() ToolsOption
TrustAnnotations maps the server's tool annotations onto agent.Safety: readOnlyHint becomes ReadOnly and idempotentHint becomes Idempotent. Pass it only for a server you trust to label its tools correctly; a mislabelled side effect would be re-run, retried, or cached.
func WithApproval ¶
func WithApproval(name string, p *agent.ApprovalPolicy) ToolsOption
WithApproval gates every call to the server's tool named name on human approval before the server sees it: p is agent.SingleApproval() for one decision (agent.Approve), or an m-of-n policy (agent.SubmitDecision, with the agent's WithApproverVerifiers). It becomes the tool's ToolSpec.Approval. Tools fails with agent.ErrConfig if p is nil or invalid, or if the server does not list a tool of that name, so a misspelt gate never leaves the real tool ungated. A later WithApproval for the same name wins. The policy is copied.
func WithCallTimeout ¶
func WithCallTimeout(d time.Duration) ToolsOption
WithCallTimeout bounds each call to a tool from Tools by d, on top of the caller's context. There is no default: without it a call waits as long as the run's context allows. d is the tool's ToolSpec.Timeout, so an agent runs each call (its tool middleware included) under that deadline; Call applies it as well, for a caller that invokes the tool directly, such as a plan flow. A call that times out has an unknown outcome (the server may still be running it), so it fails with agent.ErrToolOutcomeUnknown, and a side effect records nothing and halts on resume rather than run again; an error returned after the agent's deadline is treated the same way. A result that arrives is recorded, even after the deadline. d <= 0 sets no timeout.
func WithMaxDescriptionBytes ¶
func WithMaxDescriptionBytes(n int) ToolsOption
WithMaxDescriptionBytes sets the longest tool description, in bytes, that Tools accepts (DefaultMaxDescriptionBytes by default). A server that lists a longer one fails Tools with an error wrapping agent.ErrProtocol, never a truncated description. n <= 0 removes the limit.
func WithMaxResultBytes ¶
func WithMaxResultBytes(n int) ToolsOption
WithMaxResultBytes sets the largest result, in bytes of JSON, that a tool's Call accepts (DefaultMaxResultBytes by default). A larger result is refused with an error wrapping ErrResultTooLarge, never truncated: the tool ran, so the error is a definite failure that says so, and the model is not told the call did not happen. n <= 0 removes the limit.
func WithSafety ¶
func WithSafety(name string, s agent.Safety) ToolsOption
WithSafety sets the agent.Safety of the server's tool named name, in place of the default (a side effect) and of anything its annotations say, trusted or not. It is how an MCP tool is declared retry-safe (ReadOnly or Idempotent) by the host rather than by the server. A human approval gate is set with WithApproval. Tools fails with agent.ErrConfig if the server does not list a tool of that name, so a misspelt gate never leaves the real tool ungated. A later WithSafety for the same name wins.
Source Files