Skip to main content

​
MCP Admin API

The @radaros/transport package provides admin REST endpoints for managing MCP servers and the toolkit catalog at runtime. This enables UI-driven configuration — users can add MCP servers, connect them, and have their tools automatically available to agents.

​
Setup

​
Option 1: Via createAgentRouter

Enable admin routes with a single flag: 
import express from "express";
import { createAgentRouter } from "@radaros/transport";

const app = express();
app.use(express.json());

const router = createAgentRouter({
  agents: { assistant },
  admin: true,  // mounts /admin/* routes
});

app.use("/api", router);

​
Option 2: Standalone admin router

For more control, use createAdminRouter directly with a shared MCPManager: 
import express from "express";
import { MCPManager, createAdminRouter } from "@radaros/transport";

const mcpManager = new MCPManager();
const { router: adminRouter } = createAdminRouter({ mcpManager });

const app = express();
app.use(express.json());
app.use("/admin", adminRouter);

​
Option 3: Shared MCPManager with agent

Share the MCPManager between admin routes and your agent so tools stay in sync: 
import { Agent, openai } from "@radaros/core";
import { MCPManager, createAdminRouter } from "@radaros/transport";

const mcpManager = new MCPManager();
const { router: adminRouter } = createAdminRouter({ mcpManager });

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

// Before each chat, inject latest tools
app.post("/chat", async (req, res) => {
  const tools = await mcpManager.getAllTools();
  agent.setTools(tools);
  // ... run or stream the agent
});

​
MCP Server Endpoints

​
List servers

GET /admin/mcp

[
  {
    "id": "xhipment",
    "name": "xhipment",
    "transport": "sse",
    "url": "http://localhost:3000/mcp/sse",
    "status": "connected",
    "toolCount": 54,
    "connectedAt": "2026-02-26T10:30:00.000Z"
  }
]

​
Add a server

POST /admin/mcp
Content-Type: application/json

{
  "name": "xhipment",
  "transport": "sse",
  "url": "http://localhost:3000/mcp/sse",
  "headers": { "X-MCP-API-Key": "your-key" },
  "autoConnect": true
}
​
name
string
required
Server name. Also used as the default id.
​
transport
'stdio' | 'http' | 'sse'
required
Transport protocol.
​
url
string
Server URL (required for http and sse transports).
​
command
string
Command to spawn (required for stdio transport).
​
args
string[]
Command arguments (stdio only).
​
headers
Record<string, string>
Custom HTTP headers for authentication.
​
id
string
Custom server ID. Defaults to name.
​
autoConnect
boolean
default:"true"
Automatically connect after adding. Set false to add without connecting.
Returns the server summary with status and tool count.

​
Get server details

GET /admin/mcp/:id

​
Connect a server

POST /admin/mcp/:id/connect
Connects to the MCP server and discovers its tools. Returns the updated summary.

​
Disconnect a server

POST /admin/mcp/:id/disconnect
Disconnects the server. Tools from this server are no longer available.

​
Remove a server

DELETE /admin/mcp/:id
Disconnects (if connected) and removes the server entirely.

​
Get tools from a server

GET /admin/mcp/:id/tools

[
  {
    "name": "xhipment__get_shipments",
    "description": "[xhipment] Retrieve shipment records",
    "parameters": ["status", "dateFrom", "dateTo"]
  }
]

​
Get all tools (all connected servers)

GET /admin/mcp/tools
Returns a merged list of tools from every connected MCP server.

​
Toolkit Catalog Endpoints

The admin router also exposes the toolkit catalog, allowing UIs to list available toolkit types and instantiate them with configuration.

​
List toolkits

GET /admin/toolkits

[
  {
    "id": "github",
    "name": "GitHub",
    "description": "GitHub API integration",
    "category": "enterprise",
    "requiresCredentials": true,
    "configFields": [
      {
        "name": "token",
        "label": "GitHub Token",
        "type": "string",
        "required": true,
        "secret": true,
        "envVar": "GITHUB_TOKEN"
      }
    ]
  }
]

​
Get toolkit details

GET /admin/toolkits/:id

​
Instantiate a toolkit

POST /admin/toolkits/:id
Content-Type: application/json

{
  "token": "ghp_..."
}
The body should match the configFields schema for the toolkit. Returns the instantiated toolkit’s name and tools.

​
Server Status Values

StatusMeaning
disconnectedRegistered but not connected
connectingConnection in progress
connectedActive connection, tools available
errorConnection failed (see error field)

​
Full Example: Chat UI with MCP Management

See examples/toolkits/mcp-chat-ui.ts for a complete working example that combines:
  • Dynamic MCP server management from the browser
  • Streaming chat with SSE
  • MongoDB-backed conversation memory
  • Per-session cost tracking
import express from "express";
import { Agent, openai, MongoDBStorage, CostTracker } from "@radaros/core";
import { MCPManager, createAdminRouter } from "@radaros/transport";

const mcpManager = new MCPManager();
const { router: adminRouter } = createAdminRouter({ mcpManager });

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  memory: { storage: new MongoDBStorage("mongodb://localhost:27017/radaros"), summaries: true, userFacts: true },
  tools: [],
});

const app = express();
app.use(express.json());
app.use("/admin", adminRouter);

app.post("/chat", async (req, res) => {
  agent.setTools(await mcpManager.getAllTools());
  // ... stream the response
});