MCP
import { MCP } from "@fifthrevision/axle";
new MCP(config: MCPConfig)Conceptual guide: Tools.
Configuration
type MCPConfig = MCPStdioConfig | MCPHttpConfig;
interface MCPStdioConfig {
transport: "stdio";
name?: string;
command: string;
args?: string[];
env?: Record<string, string>;
}
interface MCPHttpConfig {
transport: "http";
name?: string;
url: string;
headers?: Record<string, string>;
}http uses the MCP streamable HTTP transport.
Properties
| Property | Type | Notes |
|---|---|---|
name | string | undefined | The configured name, falling back to the server's advertised name once connected. |
connected | boolean |
Methods
connect(options?: { span?: Span; signal?: AbortSignal }): Promise<void>
listTools(options?: { prefix?: string; span?: Span; signal?: AbortSignal }): Promise<ExecutableTool[]>
listToolDefinitions(options?: { prefix?: string; span?: Span; signal?: AbortSignal }): Promise<ToolDefinition[]>
refreshTools(): Promise<ExecutableTool[]>
close(options?: { span?: Span }): Promise<void>| Method | Notes |
|---|---|
connect() | No-op when already connected. Failures propagate. |
listTools() | Throws if not connected. Results are cached after the first call. prefix namespaces every tool name. |
listToolDefinitions() | Same, returning schema-only definitions. |
refreshTools() | Clears the cache and re-lists. Use when a server's tools change at runtime. |
close() | No-op when not connected. Clears the client, transport, and cache. |
Calling listTools() before connect() throws Error("MCP not connected. Call connect() first.") — the most common mistake here.
Use with Agent
const fs = new MCP({
transport: "stdio",
name: "fs",
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
});
await fs.connect();
const agent = new Agent({ provider, model, mcps: [fs] });
// or later:
agent.addMcp(fs);
agent.addMcps([fs, other]);The agent resolves each client's tools lazily, on the first send after registration, and only once per client instance. It passes the client's name as the tool prefix and registers the results as MCP tools in the registry.
The agent will not connect for you, so connect before the first send.
MCP tools are validated like any other tool: call arguments are parsed with the converted schema before they reach the server, and unknown top-level keys are stripped — matching a default z.object() — rather than rejected. The schema advertised to the provider carries additionalProperties: false, as vendors like OpenAI require.
Tool names mustn't collide with local or provider tools, or you'll get TOOL_REGISTRY_DUPLICATE. Giving each client a distinct name is what keeps two servers' identically-named tools apart.
Serializable configuration
MCPConfig is serializable, so it can live in your own saved recipe shape alongside the session (core carries no AgentDefinition since 0.35.0). Construct MCP instances from your recipe's mcps when rebuilding the AgentConfig — though those instances still need connecting.