Skip to main content

​
MCP Client

RadarOS 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. RadarOS 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 "@radaros/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"],
});
​
command
string
required
The command to spawn (e.g. "npx", "node", "python").
​
args
string[]
Arguments for the command.
​
env
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" },
});
​
url
string
required
The MCP server URL.
​
headers
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();
​
url
string
required
The SSE endpoint URL. The client reads this stream and discovers the POST endpoint for messages automatically.
​
headers
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 "@radaros/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 @radaros/transport: 
import { MCPManager } from "@radaros/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();
MethodDescription
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

​
name
string
required
A unique name for this MCP server connection. Used to namespace tool names.
​
transport
'stdio' | 'http' | 'sse'
required
The transport protocol to use.
MethodDescription
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.
ServerInstall
GitHubnpx -y @modelcontextprotocol/server-github
Filesystemnpx -y @modelcontextprotocol/server-filesystem
PostgreSQLnpx -y @modelcontextprotocol/server-postgres
Brave Searchnpx -y @modelcontextprotocol/server-brave-search
Slacknpx -y @modelcontextprotocol/server-slack
Browse all available servers at mcp.so.