MCP Control Plane

Overview

BrainstormRouter operates as both an MCP server and an MCP gateway:

MCP Server: Exposes 64 tools via Streamable HTTP at /v1/mcp/connect — routing, memory, agents, security, budget, and kill switch controls
MCP Gateway: Registers, discovers, governs, proxies, and audits external MCP servers

This dual-role architecture means AI agents can interact with BrainstormRouter's own capabilities through MCP, and BrainstormRouter can govern how those agents access third-party tools.

Secretless Access

When you register an external MCP server, upstream credentials (bearer tokens, API keys) are stored on the server registration — never exposed to calling agents. Agents authenticate to BrainstormRouter with their own API key or agent JWT, and BrainstormRouter injects the upstream credentials when proxying tool calls.

Agent (API key) → BrainstormRouter → (stored bearer token) → External MCP Server

This means:

Agents never see upstream secrets — credentials are isolated at the gateway level
allowed_key_ids scoping restricts which API keys can access each registered server
Agent identity propagation attributes every tool call to the calling agent in the audit trail
Credential rotation happens at the server registration, not at every agent

What's shipped vs. planned

Shipped: Credential isolation via server-stored auth profiles (bearer, API-key, OAuth2 client credentials), allowed_key_ids RBAC scoping, per-call identity attribution, periodic health polling.

Planned: OAuth-based scoped access delegation (per-tool scoping, not server-level auth), dynamic credential rotation, per-tool secret scoping.

Control-Plane Flows

1. Registry

const { server } = await client.mcp.registerServer({
  name: "Database Tools",
  transport: "streamable-http",
  url: "https://tools.example.com/mcp",
  auth: { type: "bearer", token: "secret" },
  allowed_key_ids: ["key-uuid-1"],
});

server = client.mcp.register_server({
    "name": "Database Tools",
    "transport": "streamable-http",
    "url": "https://tools.example.com/mcp",
    "auth": {"type": "bearer", "token": "secret"},
})

2. Discovery

Discover tools from a registered server by connecting via the MCP protocol and calling tools/list:

const { tools } = await client.mcp.discoverServer("server-id");
// tools: [{ name: "search", description: "...", inputSchema: {...} }]

3. Governance

Set policies on discovered tools — allow/deny and approval requirements:

await client.mcp.updatePolicy({
  tool_name: "delete_record",
  allowed: true,
  max_cost_usd: 0.5,
  requires_approval: true,
});

When a governed tool requires approval, execution returns 202 Accepted with an approval queue ID. Human operators approve or deny via the dashboard or SDK:

await client.mcp.approve("approval-id");
// or
await client.mcp.deny("approval-id");

4. Execution

Execute a tool call through the governance pipeline:

const result = await client.mcp.callTool("server-id", "search", {
  query: "recent metrics",
});

BrainstormRouter:

Validates the calling key has access (allowed_key_ids)
Checks governance policies (allowed, approval required)
Proxies the call to the upstream server with stored credentials
Logs the call with identity, result, and latency

5. Audit

Every tool call is logged with server, tool, result, latency, and calling identity:

const { entries } = await client.mcp.auditLog({ limit: 20 });
// entries: [{ timestamp, server_name, tool, result, latency_ms, api_key_id }]

Auth Profiles

External MCP servers support three auth types:

Type	Header Sent	When to Use
`bearer`	`Authorization: Bearer`	Standard bearer token auth
`api-key`	`:` (defaults to `X-API-Key`)	Custom header-based auth
`oauth2`	`Authorization: Bearer`	RFC 6749 client credentials grant with token caching

OAuth2 servers require clientId, tokenUrl, and optionally clientSecret and scopes. BrainstormRouter automatically fetches and caches access tokens, refreshing on expiry or 401 responses.

Governance Engine

The governance engine enforces policies before tool execution:

Feature	Description
Tool allow/deny	Block specific tools from being called
Approval workflows	Queue calls for human approval when `requires_approval` is set (202 Accepted)
Cost annotation	Tag policies with `max_cost_usd` for tracking (enforcement planned)
Rate limiting	Session-level rate limits (default 60 calls/min)
Approval timeout	Queued approvals auto-expire (default 5 minutes)

BrainstormRouter as MCP Server

BrainstormRouter itself is an MCP server exposing 64 tools via Streamable HTTP:

POST https://api.brainstormrouter.com/v1/mcp/connect

Tool Categories

Category	Tools	Permission
Routing & Models	`br_route_completion`, `br_list_models`, `br_get_usage`, `br_set_alias`, `br_list_aliases`, `br_patch_aliases`, `br_get_health`	`router.`, `config.`, `audit.read`
Memory	`br_memory_list`, `br_memory_store`, `br_memory_query`	`memory.*`
Config	`br_list_prompts`, `br_list_presets`, `br_list_config`, `br_get_config`, `br_set_config`	`config.*`
Ops & Insights	`br_get_ops_status`, `br_get_insights`, `br_get_governance`, `br_get_insights_daily`, `br_get_insights_forecast`	`router.read`, `audit.read`
Agents	`br_list_agents`, `br_get_leaderboard`, `br_bootstrap_agent`, `br_agent_status`, `br_agent_limits`, `br_agent_anomaly`	`agent.*`
Delegation	`br_delegate_agent`, `br_list_sub_agents`, `br_terminate_sub_agent`	`agent.delegate`
Capacity	`br_get_capacity`	`router.read`
Security	`br_get_security_status`, `br_get_policies`, `br_test_policy`	`security.read`
Budget	`br_get_budget_status`, `br_get_budget_forecast`	`audit.read`
Kill Switch	`br_activate_killswitch`, `br_deactivate_killswitch`, `br_get_killswitch_status`	`security.*`
Platform Admin	`br_list_tenants`, `br_approve_tenant`, `br_reject_tenant`, `br_get_business_digest`, `br_create_invite_code`	`platform.admin`

Kill Switch Enforcement

When the kill switch is active, only governance-related tools remain callable (br_get_budget_status, br_get_budget_forecast, br_activate_killswitch, br_deactivate_killswitch, br_get_killswitch_status). All other tools return an error.

REST API

All endpoints require API key authentication (Authorization: Bearer br_live_...).

Server Management

Method	Endpoint	Description
POST	`/v1/mcp/servers`	Register an external MCP server
GET	`/v1/mcp/servers`	List registered servers
GET	`/v1/mcp/servers/:id`	Get server details + tools
PUT	`/v1/mcp/servers/:id`	Update server config
DELETE	`/v1/mcp/servers/:id`	Remove a server
POST	`/v1/mcp/servers/:id/discover`	Discover tools from server

Tool Execution

Method	Endpoint	Description
GET	`/v1/mcp/tools`	List all tools across servers
POST	`/v1/mcp/tools/:server/:tool`	Execute a tool call

Governance

Method	Endpoint	Description
GET	`/v1/mcp/governance`	Governance engine status
GET	`/v1/mcp/approvals`	List pending approvals
POST	`/v1/mcp/approvals/:id/approve`	Approve a queued call
POST	`/v1/mcp/approvals/:id/deny`	Deny a queued call
PUT	`/v1/mcp/governance/policy`	Update a tool policy

Audit

Method	Endpoint	Description
GET	`/v1/mcp/audit`	Tool call audit log

MCP Server (BrainstormRouter as MCP Server)

Method	Endpoint	Description
POST	`/v1/mcp/connect`	Streamable HTTP transport endpoint
GET	`/v1/mcp/connect`	Server info and tool list