criogenai
criogenai

TypeScript API: MCP servers

Tools from Model Context Protocol servers, over HTTP or a local process. Generated from the declarations and doc comments of criogenai 0.1.7. See also: TypeScript API overview, the same module in Python.

Tools from MCP servers.

import { Agent, mcp } from "criogenai";
const files = await mcp.stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."]);
const agent = new Agent({ model, tools: [files] });          // all its tools
// or tools: [files.tool("read_file")]
await files.close();

The client runs in the Rust engine: it speaks MCP 2026-07-28 and falls back to the initialize handshake of older servers; stdio servers are started as a process (and again if they exit). It only uses tools: a server cannot sample your model or read your files. In criogenai/web only mcp.http works.

What a server says is data: names are mapped to names models accept (set prefix to keep two servers apart), schemas and messages are bounded, and its readOnlyHint / idempotentHint decide nothing unless trustAnnotations. Header and env values never appear in an error.

import { mcp } from "criogenai";
mcp.stdio
import {
  McpServer,
  McpOptions,
  StdioOptions,
  HttpOptions,
  McpInfo,
  McpTool,
} from "criogenai";

These are used as mcp.<name>. Also exported at the top level: McpServer, McpOptions, StdioOptions, HttpOptions, McpInfo, McpTool.

Contents#

NameKindSummary
McpServerclassA connected MCP server: get one with mcp.stdio or mcp.http.
McpOptionsinterfaceOptions for every MCP server.
stdiofunctionStarts command with args as an MCP server (stdio) and lists its tools.
httpfunctionConnects to the MCP server at url (Streamable HTTP) and lists its tools.
StdioOptionsinterfaceA server this app starts (not in the browser).
HttpOptionsinterfaceA server at a URL (Streamable HTTP).
McpInfointerfaceWhat the server said about itself.
McpToolclassOne tool of a connected server; put it in an agent's tools.

McpServer#

class McpServer {
  constructor(name: string);
}

A connected MCP server: get one with mcp.stdio or mcp.http.

Put the server in an agent's tools for all its tools, or pick some with server.tool(name). MCP tools work like any other tool: approvals, timeouts, limits, hooks and the audit trail apply. Close it with close() (or await using).

Parameters

  • name (string): The server's name in errors: name, else prefix, else the command or URL. The server's name in errors.

Example

import { Agent, mcp } from "criogenai";

// Starts the server as a process (needs Node's npx and network access to fetch it).
const files = await mcp.stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."], { prefix: "files" });
console.log(files.tools.map((t) => t.name)); // e.g. ["files_read_file", ...]
const agent = new Agent({ model: "openai:gpt-5-mini", tools: [files] });
console.log((await agent.run("What is in README.md?")).text);
await files.close();

McpServer.info#

info: McpInfo

What the server said about itself when it connected.

McpServer.tools#

tools: McpTool[]

Its tools, as the agent sees them (after only, exclude and prefix).

McpServer.instructions#

readonly instructions: string | null

The server's instructions for models (not added to any prompt).

McpServer.tool#

tool(name: string): McpTool

The tool the agent sees as name.

Parameters

  • name (string): The tool's name as the agent sees it (with the prefix).

Raises

  • Error: The server has no such tool; the message lists its tools.

McpServer.refresh#

refresh(): Promise<void>

Lists the tools again (agents already built keep theirs).

McpServer.call#

call(name: string, args?: Record<string, unknown>): Promise<unknown>

Calls a tool directly: its text, its JSON value, or its content blocks. Throws ToolError when the tool fails.

Parameters

  • name (string): The tool's name as the agent sees it (with the prefix).
  • args (Record<string, unknown>, default {}): The tool's arguments.

Returns: The tool's text, its JSON value (structuredContent), or its content blocks.

Raises

  • ToolError: The tool reported a failure (isError); the message is the server's.

Example

import { mcp } from "criogenai";

const server = await mcp.http("https://mcp.example.com/mcp", { headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` } });
const answer = await server.call("search_docs", { query: "rate limits" });
await server.close();

McpServer.close#

close(): Promise<void>

Stops the server (a process: stdin closed, killed after 2 s).

McpOptions#

interface McpOptions {
  name?: string;
  prefix?: string;
  timeoutSecs?: number;
  connectTimeoutSecs?: number;
  maxMessageBytes?: number;
  trustAnnotations?: boolean;
  only?: string[];
  exclude?: string[];
}

Options for every MCP server.

Fields

  • name (string, optional): The server's name in errors (default: the prefix, else the command or host).
  • prefix (string, optional): The agent sees <prefix>_<tool>: keeps two servers' tools apart.
  • timeoutSecs (number, optional): Seconds one call may take. Default 60.
  • connectTimeoutSecs (number, optional): Seconds to be ready. Default 30.
  • maxMessageBytes (number, optional): The largest message read from the server. Default 4 MiB.
  • trustAnnotations (boolean, optional): Believe the server's readOnlyHint / idempotentHint (they decide retries). Default false.
  • only (string[], optional): Only these tools (the server's names).
  • exclude (string[], optional): Leave these tools out (the server's names).

stdio#

function stdio(command: string, args?: string[], options?: StdioOptions): Promise<McpServer>

Starts command with args as an MCP server (stdio) and lists its tools. Servers only.

The process inherits this process's environment plus env. If it exits, the next call starts it again. In the browser (criogenai/web) this throws unsupported.

Parameters

  • command (string): The program, e.g. "npx" or "python".
  • args (string[], default []): Its arguments.
  • options (StdioOptions, default {}): Environment, working directory, prefix, timeouts, limits and which tools to keep.

Returns: The connected server.

Example

import { mcp } from "criogenai";

const files = await mcp.stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."], {
  prefix: "files",
  only: ["read_file", "list_directory"],
});
console.log(files.info.name, files.tools.length);
await files.close();

http#

function http(url: string, options?: HttpOptions): Promise<McpServer>

Connects to the MCP server at url (Streamable HTTP) and lists its tools. Use https; plain http only to this computer when headers are set.

Works in both engines, the browser included. Pass a token in headers; header values never appear in an error.

Parameters

  • url (string): The server's endpoint, e.g. "https://mcp.example.com/mcp".
  • options (HttpOptions, default {}): Headers, prefix, timeouts, limits and which tools to keep.

Returns: The connected server.

Example

import { Agent, mcp } from "criogenai";

const docs = await mcp.http("https://mcp.example.com/mcp", {
  headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
  prefix: "docs",
});
const agent = new Agent({ model: "openai:gpt-5-mini", tools: [docs] });

StdioOptions#

interface StdioOptions extends McpOptions {
  env?: Record<string, string>;
  cwd?: string;
}

A server this app starts (not in the browser).

Fields

  • env (Record<string, string>, optional): Added to this process's environment.
  • cwd (string, optional): The server process's working directory; default this process's.
  • name (string, optional): The server's name in errors (default: the prefix, else the command or host).
  • prefix (string, optional): The agent sees <prefix>_<tool>: keeps two servers' tools apart.
  • timeoutSecs (number, optional): Seconds one call may take. Default 60.
  • connectTimeoutSecs (number, optional): Seconds to be ready. Default 30.
  • maxMessageBytes (number, optional): The largest message read from the server. Default 4 MiB.
  • trustAnnotations (boolean, optional): Believe the server's readOnlyHint / idempotentHint (they decide retries). Default false.
  • only (string[], optional): Only these tools (the server's names).
  • exclude (string[], optional): Leave these tools out (the server's names).

HttpOptions#

interface HttpOptions extends McpOptions {
  headers?: Record<string, string>;
}

A server at a URL (Streamable HTTP).

Fields

  • headers (Record<string, string>, optional): Sent with every request, e.g. { Authorization: "Bearer …" }.
  • name (string, optional): The server's name in errors (default: the prefix, else the command or host).
  • prefix (string, optional): The agent sees <prefix>_<tool>: keeps two servers' tools apart.
  • timeoutSecs (number, optional): Seconds one call may take. Default 60.
  • connectTimeoutSecs (number, optional): Seconds to be ready. Default 30.
  • maxMessageBytes (number, optional): The largest message read from the server. Default 4 MiB.
  • trustAnnotations (boolean, optional): Believe the server's readOnlyHint / idempotentHint (they decide retries). Default false.
  • only (string[], optional): Only these tools (the server's names).
  • exclude (string[], optional): Leave these tools out (the server's names).

McpInfo#

interface McpInfo {
  name: string | null;
  version: string | null;
  protocolVersion: string;
  instructions: string | null;
}

What the server said about itself.

Fields

  • name (string | null): The server's name, if it gave one.
  • version (string | null): The server's version, if it gave one.
  • protocolVersion (string): The MCP version both sides agreed on, e.g. "2026-07-28".
  • instructions (string | null): Its instructions for models (not added to any prompt).

McpTool#

class McpTool {
  constructor(server: McpServer, spec: { name: string; description: string; schema: Record<string, unknown>; read_only: boolean; destructive: boolean; idempotent: boolean; });
}

One tool of a connected server; put it in an agent's tools. Get it with server.tool(name) or from server.tools.

Parameters

  • server (McpServer): The server it belongs to.
  • spec ({ name: string; description: string; schema: Record<string, unknown>; read_only: boolean; destructive: boolean; idempotent: boolean; }): The tool as the engine describes it.

McpTool.name#

readonly name: string

The name the agent sees: mapped to what model APIs accept, with the server's prefix.

McpTool.description#

readonly description: string

The server's description of the tool (cut to 8,000 characters).

McpTool.schema#

readonly schema: Record<string, unknown>

The JSON Schema of its arguments.

McpTool.readOnly#

readonly readOnly: boolean

The server's readOnlyHint; always false unless trustAnnotations is set.

McpTool.destructive#

readonly destructive: boolean

The server's destructiveHint (kept without trustAnnotations: it only makes CriogenAI more careful).

McpTool.idempotent#

readonly idempotent: boolean

The server's idempotentHint (or readOnlyHint); always false unless trustAnnotations is set. Idempotent tools are retried after a failure.

McpTool.call#

call(args?: Record<string, unknown>): Promise<unknown>

Calls it directly (see McpServer.call).

Parameters

  • args (Record<string, unknown>, default {}): The tool's arguments.

Raises

  • ToolError: The tool reported a failure.