MCP API

agent.mcp has one property per configured MCP server and one method per tool: await agent.mcp.<server>.<tool>(args). The guide agents read, with configuration and sign-in, is on MCP servers.

Types#

As declared in the repl.d.ts the skills ship. Constructors are left out: code in a cell is handed these objects and doesn’t build them.

• Mcp
• McpServer
• McpToolError
• McpInputRequiredError
• McpServersResult
• McpServerMethods
• McpToolFunction
• McpInputRequest
• McpServerStatus
• McpToolsResult
• McpCallOptions
• McpToolResult
• McpTool
• McpToolChange
• McpInputResponse

class Mcp {
	/** Every configured server with its connection state; the config file's error, if it has one. */
	list(): Promise<McpServersResult>;
	/** Re-read mcp.json now; edits are otherwise picked up on the next call. */
	reload(): Promise<McpServersResult>;
	server(name: string): McpServer;
}

/** One configured server. Any other property is a tool: `await agent.mcp.linear.list_issues({ team: "ENG" })`. */
type McpServer = McpServerMethods & {
	[tool: string]: McpToolFunction;
};

/** Thrown when a tool reports `isError`; the server's text is the message. */
class McpToolError extends Error {
	readonly server: string;
	readonly tool: string;
	readonly content: Record<string, unknown>[];
}

/**
 * Thrown when the tool asked for something only the user can give and the
 * call carried no answer. Retry the same call with `inputResponses`.
 */
class McpInputRequiredError extends Error {
	readonly server: string;
	readonly tool: string;
	readonly requests: McpInputRequest[];
}

type McpServersResult = {
	configPath: string;
	configError: string | null;
	servers: McpServerStatus[];
};

type McpServerMethods = {
	readonly name: string;
	/** The server's tools with their JSON schemas, plus what changed since Codemode last listed them. */
	tools(): Promise<McpToolsResult>;
	/** Call a tool by name; the form to use when the name is not a valid property. */
	call(tool: string, args?: Record<string, unknown>, options?: McpCallOptions): Promise<McpToolResult>;
};

type McpToolFunction = (args?: Record<string, unknown>, options?: McpCallOptions) => Promise<McpToolResult>;

type McpInputRequest = {
	mode: "form";
	id: string;
	message: string;
	requestedSchema: Record<string, unknown>;
} | {
	mode: "url";
	id: string;
	message: string;
	url: string;
};

type McpServerStatus = {
	name: string;
	transport: "http" | "stdio";
	status: "error" | "connected" | "connecting" | "idle";
	auth: "notRequired" | "signedIn" | "signedOut" | "signingIn";
	error: string | null;
	toolCount: number | null;
};

type McpToolsResult = {
	server: {
		name: string;
		implementation: {
			name: string;
			version: string;
		} | null;
		instructions: string | null;
	};
	tools: McpTool[];
	changes: McpToolChange[];
};

type McpCallOptions = {
	/** Default 60000. The daemon extends it while the server reports progress. */
	timeoutMs?: number;
	/** Answers to the requests an earlier attempt raised as `McpInputRequiredError`, by request id. */
	inputResponses?: Record<string, McpInputResponse>;
};

type McpToolResult = {
	/** Every text block of the result, joined with newlines. */
	text: string;
	/** The raw content blocks; pass the whole result to `agent.viewImage` to show an image block. */
	content: Record<string, unknown>[];
	/** Present when the tool declares an output schema. */
	structuredContent: unknown;
};

type McpTool = {
	name: string;
	title: string | null;
	description: string;
	inputSchema: Record<string, unknown>;
	outputSchema: Record<string, unknown> | null;
	annotations: Record<string, unknown> | null;
};

type McpToolChange = {
	name: string;
	change: "added" | "changed" | "removed";
};

type McpInputResponse = {
	action: "accept";
	content?: Record<string, unknown>;
} | {
	action: "decline";
} | {
	action: "cancel";
};