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)

Method	Path	Auth	RBAC	Description
POST	`/v1/mcp/servers`	API Key	—	Register a server
GET	`/v1/mcp/servers`	API Key	—	List servers
GET	`/v1/mcp/servers/:id`	API Key	—	Get server detail
PUT	`/v1/mcp/servers/:id`	API Key	—	Update server
DELETE	`/v1/mcp/servers/:id`	API Key	—	Remove server
POST	`/v1/mcp/servers/:id/discover`	API Key	—	Discover tools
GET	`/v1/mcp/tools`	API Key	—	List all tools
POST	`/v1/mcp/tools/:server/:tool`	API Key	—	Execute a tool
GET	`/v1/mcp/audit`	API Key	—	Tool call audit log
GET	`/v1/mcp/governance`	API Key	`security.read`	Governance engine status
GET	`/v1/mcp/approvals`	API Key	`security.read`	List pending approvals
POST	`/v1/mcp/approvals/:id/approve`	API Key	`security.write`	Approve a tool call
POST	`/v1/mcp/approvals/:id/deny`	API Key	`security.write`	Deny a tool call
PUT	`/v1/mcp/governance/policy`	API Key	`security.write`	Update a tool policy

MCP Server (BrainstormRouter as MCP Server)

Method	Path	Auth	Description
POST	`/v1/mcp/connect`	API Key	Streamable HTTP transport endpoint
GET	`/v1/mcp/connect`	API Key	Server info and available tool list

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

Field	Type	Required	Description
`name`	string	Yes	Server display name
`transport`	string	Yes	`streamable-http` or `sse` (legacy)
`url`	string	Yes	Server URL
`auth`	object	No	`{type, token, headerName}`
`auth.type`	string	No	`bearer` or `api-key`
`auth.token`	string	No	Token or key value
`auth.headerName`	string	No	Custom header name (api-key type only)
`allowed_key_ids`	string[]	No	RBAC: which API keys can use this server

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

Field	Type	Required	Description
`tool_name`	string	Yes	Name of the tool to set policy for
`allowed`	boolean	Yes	Whether the tool is allowed to execute
`max_cost_usd`	number	No	Maximum cost per invocation in USD
`requires_approval`	boolean	No	If true, tool calls are queued for approval

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.