MCP Gateway

Register and proxy external MCP servers with RBAC, governance, and audit logging. Also exposes BrainstormRouter itself as an MCP server.

Endpoints

MCP Gateway (Proxy External Servers)

MCP Server (BrainstormRouter as MCP Server)

Register a server

curl -X POST https://api.brainstormrouter.com/v1/mcp/servers \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Tools",
    "transport": "streamable-http",
    "url": "https://tools.example.com/mcp",
    "auth": {"type": "bearer", "token": "secret"},
    "allowed_key_ids": ["key-uuid-1"]
  }'

Request body

Transport types

• streamable-http — Current MCP standard. Connects to the server over HTTP with bidirectional streaming.
• sse — Legacy transport. Server-Sent Events based. Still supported but new integrations should use streamable-http.

Auth types

• bearer — Sends Authorization: Bearer header on every request to the upstream server.
• api-key — Sends the token in a custom header (defaults to X-API-Key if headerName is not set).

Discover tools

Connects to a registered MCP server, calls tools/list via the Streamable HTTP transport, and saves the discovered tools.

curl -X POST https://api.brainstormrouter.com/v1/mcp/servers/server-uuid/discover \
  -H "Authorization: Bearer br_live_..."

{
  "tools": [
    {
      "name": "search",
      "description": "Search the database",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      }
    }
  ],
  "count": 1
}

Execute a tool

curl -X POST https://api.brainstormrouter.com/v1/mcp/tools/server-uuid/search \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"query": "recent metrics"}}'

{
  "result": {"matches": [...]},
  "metadata": {
    "server_id": "server-uuid",
    "tool": "search",
    "latency_ms": 45
  }
}

Governance responses

When the governance engine is enabled, tool execution may return non-200 status codes:

• 403 Forbidden — The governance policy denies execution of this tool.
• 202 Accepted — The tool call has been queued for human approval. The response body contains the approval request ID.

{
  "status": "queued",
  "approval_id": "approval-uuid",
  "message": "Tool call requires approval"
}

RBAC

Set allowed_key_ids on a server to restrict which API keys can call its tools. An empty list means all keys have access.

Governance endpoints have their own RBAC requirements:

• Read endpoints (GET /v1/mcp/governance, GET /v1/mcp/approvals) require the security.read permission.
• Write endpoints (POST /v1/mcp/approvals/:id/approve, POST /v1/mcp/approvals/:id/deny, PUT /v1/mcp/governance/policy) require the security.write permission.

Governance

Get governance status

Returns the current state of the governance engine, including active policies and the number of pending approvals.

curl https://api.brainstormrouter.com/v1/mcp/governance \
  -H "Authorization: Bearer br_live_..."

When governance is configured:

{
  "enabled": true,
  "policies": [
    {
      "tool_name": "delete_record",
      "allowed": false,
      "requires_approval": true,
      "max_cost_usd": 1.0
    }
  ],
  "pending_approvals": 3
}

When governance is not configured:

{
  "enabled": false,
  "message": "Governance engine not configured"
}

Update a tool policy

curl -X PUT https://api.brainstormrouter.com/v1/mcp/governance/policy \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "delete_record",
    "allowed": true,
    "max_cost_usd": 0.50,
    "requires_approval": true
  }'

Request body

Approvals

List pending approvals

Returns tool calls that are queued and awaiting human approval.

curl https://api.brainstormrouter.com/v1/mcp/approvals \
  -H "Authorization: Bearer br_live_..."

{
  "approvals": [
    {
      "id": "approval-uuid",
      "timestamp": "2025-06-15T14:22:00.000Z",
      "server_id": "server-uuid",
      "server_name": "Database Tools",
      "tool": "delete_record",
      "arguments": { "record_id": "rec-123" },
      "status": "pending",
      "api_key_id": "key-uuid"
    }
  ],
  "count": 1
}

Approve a tool call

curl -X POST https://api.brainstormrouter.com/v1/mcp/approvals/approval-uuid/approve \
  -H "Authorization: Bearer br_live_..."

{
  "id": "approval-uuid",
  "status": "approved",
  "result": { "deleted": true }
}

Deny a tool call

curl -X POST https://api.brainstormrouter.com/v1/mcp/approvals/approval-uuid/deny \
  -H "Authorization: Bearer br_live_..."

{
  "id": "approval-uuid",
  "status": "denied"
}

Audit log

Every tool call is logged with result status and latency:

curl "https://api.brainstormrouter.com/v1/mcp/audit?limit=20" \
  -H "Authorization: Bearer br_live_..."

{
  "entries": [
    {
      "id": "audit-uuid",
      "timestamp": "2025-02-20T10:30:00.000Z",
      "server_id": "server-uuid",
      "server_name": "Database Tools",
      "tool": "search",
      "result": "success",
      "latency_ms": 45,
      "api_key_id": "key-uuid"
    }
  ],
  "count": 1
}

BrainstormRouter as MCP Server

BrainstormRouter exposes its own capabilities as an MCP server via the Streamable HTTP transport at /v1/mcp/connect.

Connect

curl -X POST https://api.brainstormrouter.com/v1/mcp/connect \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}},"id":1}'

A new server instance is created per request (stateless). Auth context is resolved from the API key and passed to tool handlers — no principal is cached on the server instance.

Server info

curl https://api.brainstormrouter.com/v1/mcp/connect \
  -H "Authorization: Bearer br_live_..."

Returns server name, version, transport type, and the list of available tools with descriptions and RBAC permissions. See the MCP Control Plane concepts page for the full tool reference.