@atoms-agent/mcp

Optional MCP Tools Client for atoms_agent, built on the official @modelcontextprotocol/sdk. Supports Stdio and Streamable HTTP transports and maps remote tools onto Core ToolDefinitions.

This package depends on @atoms-agent/core and the official MCP SDK. It does not depend on @atoms-agent/skills, and does not implement MCP Server, Resources, Prompts, Sampling, Elicitation, or auto-reconnect managers.

Server command, URL, headers, credentials, and process/network policy stay in the Host runtime — never in AgentSpec.

Install

npm install @atoms-agent/[email protected] @atoms-agent/[email protected] @atoms-agent/[email protected]

Usage

import { createAgent } from "@atoms-agent/core";
import type { ModelAdapter } from "@atoms-agent/llm";
import { createMcpClient, createMcpTools, mapMcpSideEffect } from "@atoms-agent/mcp";

// Provide any ModelAdapter (OpenAI/Anthropic/ScriptedModel/etc).
declare const model: ModelAdapter;

const client = createMcpClient({
  server: {
    transport: "stdio",
    command: "node",
    args: ["./my-mcp-server.js"],
  },
});

await client.connect();
const mcpTools = await createMcpTools({ client });

// Conservative annotation mapping:
// readOnlyHint=true (no conflict) -> none
// else idempotentHint=true (no conflict) -> idempotent
// undeclared / false / conflict -> non_idempotent
void mapMcpSideEffect;

const agent = createAgent({
  model,
  systemPrompt: "Use MCP tools when helpful.",
  tools: mcpTools,
  authorize: ({ tool }) => (tool.sideEffect === "none" ? "allow" : "deny"),
});

await client.close();

For offline demos, install @atoms-agent/testing as a dev dependency and pass createScriptedModel(...) as model.

Only import from the package root. Subpath / deep imports are not supported. Public TypeScript declarations do not re-export MCP SDK types.

Requirements

• Node.js >= 22.13
• ESM

License

MIT