MCP Client

Agentium includes a built-in MCP client that lets your agents connect to any Model Context Protocol server and use its tools natively — no glue code required.

MCP is an open protocol that standardizes how LLM applications integrate with external tools, resources, and prompts. Agentium acts as an MCP client, consuming tools from external MCP servers.

Installation

The MCP SDK is an optional peer dependency:

npm install @modelcontextprotocol/sdk

Quick Start

import { Agent, openai, MCPToolProvider } from "@agentium/core";

// Connect to a GitHub MCP server via stdio
const github = new MCPToolProvider({
  name: "github",
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
});

await github.connect();

const agent = new Agent({
  name: "dev-assistant",
  model: openai("gpt-4o"),
  instructions: "You are a developer assistant with GitHub access.",
  tools: [...await github.getTools()],
});

const result = await agent.run("What are the open issues in my repo?");
console.log(result.text);

await github.close();

Transports

stdio

Spawns the MCP server as a child process and communicates via stdin/stdout. Best for local MCP servers.

const tools = new MCPToolProvider({
  name: "filesystem",
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
});

string

required

The command to spawn (e.g. "npx", "node", "python").

string[]

Arguments for the command.

Record<string, string>

Environment variables passed to the spawned process.

HTTP (Streamable HTTP)

Connects to a remote MCP server over HTTP. Falls back to SSE transport if Streamable HTTP is not available.

const tools = new MCPToolProvider({
  name: "database",
  transport: "http",
  url: "http://localhost:8080/mcp",
  headers: { Authorization: "Bearer my-token" },
});

string

required

The MCP server URL.

Record<string, string>

Custom HTTP headers (e.g. for authentication).

SSE (Server-Sent Events)

For MCP servers that use separate /sse and /messages endpoints. The client opens a persistent SSE stream for receiving responses and sends JSON-RPC requests via POST. Use this when your server implements the async SSE pattern.

const mcp = new MCPToolProvider({
  name: "xhipment",
  transport: "sse",
  url: "http://localhost:3000/mcp/sse",
  headers: {
    "X-MCP-API-Key": "your-api-key",
  },
});

await mcp.connect();
const tools = await mcp.getTools();

string

required

The SSE endpoint URL. The client reads this stream and discovers the POST endpoint for messages automatically.

Record<string, string>

Custom HTTP headers sent on both the SSE connection and POST requests.

Mixing MCP and Local Tools

MCP tools are returned as standard ToolDef[] and can be combined with local tools:

import { defineTool } from "@agentium/core";
import { z } from "zod";

const localTool = defineTool({
  name: "current_time",
  description: "Returns the current date and time",
  parameters: z.object({}),
  execute: async () => new Date().toISOString(),
});

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  tools: [
    ...await github.getTools(),    // MCP tools
    ...await dbTools.getTools(),    // Another MCP server
    localTool,                      // Local tool
  ],
});

Multiple MCP Servers

Connect to multiple servers simultaneously. Tool names are namespaced as {serverName}__{toolName} to avoid collisions:

const github = new MCPToolProvider({ name: "github", ... });
const slack = new MCPToolProvider({ name: "slack", ... });

await Promise.all([github.connect(), slack.connect()]);

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  tools: [
    ...await github.getTools(),  // github__create_issue, github__list_repos, ...
    ...await slack.getTools(),   // slack__send_message, slack__list_channels, ...
  ],
});

Handling Large Tool Results

MCP servers often return bulk data (e.g. all outstanding invoices, full record sets). A single tool result can be 200KB+, which translates to 50K+ prompt tokens on the next LLM roundtrip. Use toolResultLimit to automatically truncate or summarize oversized results before they reach the main model:

const agent = new Agent({
  name: "assistant",
  model: anthropic("claude-sonnet-4-6"),
  tools: [...await mcp.getTools()],
  toolResultLimit: {
    maxChars: 20000,
    strategy: "summarize",
    model: anthropic("claude-haiku-4-5-20251001"),
  },
});

This is especially important when combining toolResultLimit with toolRouter — the router selects which tools to call, and the result limit controls how much data comes back. Together they can reduce prompt tokens by 95%+. See Tool Result Limits for full configuration details.

Dynamic Tools with `setTools()`

When MCP servers are connected or disconnected at runtime, use agent.setTools() to hot-swap the tool set without recreating the agent:

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  tools: [],
});

// Later, after MCP servers connect...
const mcpTools = await mcp.getTools();
agent.setTools(mcpTools);

// Agent now uses the updated tools on the next run

MCPManager (Multi-Server Lifecycle)

For managing multiple MCP servers at runtime — adding, connecting, disconnecting, and collecting tools — use MCPManager from @agentium/transport:

import { MCPManager } from "@agentium/transport";

const mcpManager = new MCPManager();

// Add and connect a server
mcpManager.add({
  name: "xhipment",
  transport: "sse",
  url: "http://localhost:3000/mcp/sse",
  headers: { "X-MCP-API-Key": "your-key" },
});
await mcpManager.connect("xhipment");

// Add another server
mcpManager.add({
  name: "github",
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
});
await mcpManager.connect("github");

// Get all tools from all connected servers
const allTools = await mcpManager.getAllTools();
agent.setTools(allTools);

// List server statuses
const servers = mcpManager.list();
// [{ id: "xhipment", status: "connected", toolCount: 54 }, ...]

// Disconnect a specific server
await mcpManager.disconnect("github");

// Clean up all
await mcpManager.closeAll();

Method	Description
`add(config, id?)`	Register a server. Returns summary.
`connect(id)`	Connect and discover tools.
`disconnect(id)`	Disconnect a server.
`remove(id)`	Remove a server entirely.
`getAllTools()`	Merged `ToolDef[]` from all connected servers.
`getTools(id)`	Tools from a single server.
`list()`	All server summaries (id, status, toolCount).
`has(id)`	Check if a server is registered.
`closeAll()`	Disconnect all servers.

For managing MCP servers via REST API (from a UI), see MCP Admin.

API Reference

MCPToolProvider

string

required

A unique name for this MCP server connection. Used to namespace tool names.

'stdio' | 'http' | 'sse'

required

The transport protocol to use.

Method	Description
`connect()`	Connect to the MCP server and discover tools.
`getTools()`	Returns `ToolDef[]` — all discovered tools.
`refresh()`	Re-discover tools from the server.
`close()`	Disconnect from the server and clean up.

Popular MCP Servers

Server	Install
GitHub	`npx -y @modelcontextprotocol/server-github`
Filesystem	`npx -y @modelcontextprotocol/server-filesystem`
PostgreSQL	`npx -y @modelcontextprotocol/server-postgres`
Brave Search	`npx -y @modelcontextprotocol/server-brave-search`
Slack	`npx -y @modelcontextprotocol/server-slack`

Browse all available servers at mcp.so.

​MCP Client

​Installation

​Quick Start

​Transports

​stdio

​HTTP (Streamable HTTP)

​SSE (Server-Sent Events)

​Mixing MCP and Local Tools

​Multiple MCP Servers

​Handling Large Tool Results

​Dynamic Tools with setTools()

​MCPManager (Multi-Server Lifecycle)

​API Reference

​MCPToolProvider

​Popular MCP Servers

MCP Client

Installation

Quick Start

Transports

stdio

HTTP (Streamable HTTP)

SSE (Server-Sent Events)

Mixing MCP and Local Tools

Multiple MCP Servers

Handling Large Tool Results

Dynamic Tools with `setTools()`

MCPManager (Multi-Server Lifecycle)

API Reference

MCPToolProvider

Popular MCP Servers