Overview for Developers

Brutor is a gateway. You don’t rewrite your application to use it — you change one base URL and your existing OpenAI SDK, Anthropic SDK, MCP client, or plain HTTP code keeps working. The moment your traffic flows through the gateway, it picks up, with zero agent-side code:

• Guardrails — prompt-injection and jailbreak detection, PII redaction or blocking, secrets detection, toxic-content filtering, banned words — on inputs and outputs across every surface. See Guardrails.
• Budgets and limits — requests-per-minute, tokens-per-day, dollars-per-minute, concurrency caps, per group and per model. See Limits.
• Failover and routing — routing groups retry, cool down failing models, and fall back to secondaries without your code noticing.
• Audit trail — every request, tool call, block, and approval decision is logged with cost, latency, and the identity that made it. See Logs.
• Cost tracking — per-token cost attribution by user, group, and model in Mission Control.
• Human-in-the-loop approvals — sensitive tool calls pause until a group member approves them. See Approvals.

# Before
client = OpenAI(api_key="sk-...")

# After — same code, now governed
client = OpenAI(
    api_key="sk_brutor_api_...",
    base_url="http://localhost:8100/v1/proxy/llm",
)

The runtime surfaces

All developer-facing runtime traffic goes to the Core Proxy (Rust, port 8100). The Control Plane (5050) is admin-only configuration — you only touch it from setup scripts or the Admin UI.

                        ┌──────────────────────────────────────────┐
  Your app / agent ────▶│           Core Proxy  :8100              │
                        │                                          │
  OpenAI SDK ──────────▶│  /v1/proxy/llm/*        LLM (OpenAI-compat)
  Anthropic SDK ───────▶│  /v1/messages           LLM (Anthropic native)
  MCP client ──────────▶│  /v1/proxy/mcp/{id}     MCP tool servers
  MCP client ──────────▶│  /v1/proxy/vmcp/{id}    Virtual MCP (aggregated)
  A2A peer ────────────▶│  /a2a/{tenant}/{card}   Agent-to-Agent v1.0
  Agent runtime ───────▶│  /v1/proxy/mcp/system-  Agent Skills (MCP,
                        │    agent-skill-server-* progressive disclosure)
  OAuth client ────────▶│  /v1/proxy/oauth/*      OAuth proxy for MCP tools
  Custom portal ───────▶│  /v1/portal/*           Portal API (end-user auth,
                        │                         models, approvals, notifications)
                        └──────────────────────────────────────────┘
                                          │
                            guardrails · limits · routing
                            approvals · audit · cost tracking

Surface	Base path	What it’s for
LLM proxy	/v1/proxy/llm	OpenAI-compatible chat, completions, responses, embeddings, images, audio, video
Anthropic native	/v1/messages	Anthropic SDK and Claude Code, unmodified
MCP	/v1/proxy/mcp/{server_id}	JSON-RPC 2.0 to any registered MCP server (streamable HTTP)
Virtual MCP	/v1/proxy/vmcp/{virtual_server_id}	One endpoint aggregating tools from many MCP servers
A2A v1.0	/a2a/{tenant_id}/{card_name}	Agent-to-Agent messaging, tasks, signed agent cards
Agent Skills	/v1/proxy/mcp/system-agent-skill-server-{tenant}	Progressive-disclosure skills over MCP — load instructions, run scripts in the governed sandbox
OAuth proxy	/v1/proxy/oauth/{mcp_server_id}/{idp_server_id}	Per-user OAuth for SaaS-backed MCP tools
Portal API	/v1/portal/*	End-user auth, model/server discovery, approvals, notifications — the API the shipped User Portal runs on

Authentication: API key or portal JWT

There are two developer-relevant credentials, resolved in this priority order:

Credential	Header	Who uses it	How you get it
API key	Authorization: Bearer sk_brutor_api_... or X-API-Key: sk_brutor_api_...	Agents, scripts, CLIs, backend services	Admin UI → Resource Group → API Keys, or via the Admin API
Portal JWT	Authorization: Bearer <jwt> (or X-Gateway-Authorization: Bearer <jwt>)	End users in a portal/chat client you build	POST /v1/portal/auth/login with the user’s username/password

API keys are sk_brutor_api_ + 43 URL-safe characters, stored SHA256-hashed server-side, and bound to a resource group — the key is the governance scope. Portal JWTs are HS256 tokens minted by the Core Proxy at login; they carry the user’s identity, and the user’s group memberships determine what models and tools they can reach.

Two more headers matter on multi-tenant installs:

Header	Example	Purpose
X-Tenant-ID	default	Tenant context when it can’t be derived from the credential
X-Resource-Group	rg-01ABC...	Pin the request to one of the caller’s groups (defaults to primary group, then first membership)

Tip

Responses from governed surfaces carry X-Usage-Warning headers when a budget or quota threshold is approaching (e.g. Daily budget at 85%: $4.25 / $5.00) — watch them to back off before you hit a hard 429.

Which surface do I use?

I want my app or agent to call an LLM → point your OpenAI/Anthropic SDK at the gateway. One base-URL change.

I want my agent to use tools (CRM, Slack, databases…) → call registered MCP servers through /v1/proxy/mcp/{server_id}, or aggregate many behind one Virtual MCP endpoint.

I’m building a chat UI for end users → build on the Portal API: login, model pickers, streaming chat, approval inbox, notifications.

I have a REST tool of my own → wrap it as an MCP server (a few dozen lines with FastMCP), register it, and every agent in the org can use it — governed.

My agent needs to talk to other agents → publish a signed A2A agent card and exchange messages through the gateway.

I want reusable, versioned automation with human approval gates → package it as an Agent Skill.

Call LLMs through the gatewayOpenAI-compatible + Anthropic-native endpoints, streaming, tool calling, error handling.

Build an agentA LangGraph agent using the gateway for both LLM calls and MCP tools, with approval handling.

Use MCP tools through the gatewayConnect Claude Desktop, Goose, or any MCP SDK client to governed servers.

Coding agents through the gatewayClaude Code and OpenAI-compatible CLIs — governed with one environment variable.

Register your own MCP serverBuild a FastMCP server, register it, assign it to a resource group, call it.

Build a custom portalThe full Portal API walkthrough: login, workspaces, streaming chat, approvals, notifications.

A2A agentsSigned agent cards, message:send / message:stream, task lifecycle.

Agent SkillsProgressive disclosure over MCP — skills__load instructions, run scripts in the governed sandbox; RG-based access.

Knowledge bases & RAGCollections, async ingestion, hybrid retrieval — LLM calls grounded automatically per resource group.

OAuth for MCP toolsPer-user OAuth to SaaS tools — real tokens never leave the gateway.

Provision with a setup scriptIdempotent provisioning of users, groups, models, keys, and guardrails from CI.

A note on scope

Brutor governs traffic that points at the gateway: API calls, agents, internal apps, CLIs, portals — across every provider and resource you register. The moment a client (your agent, curl, Goose, Claude Code, a custom portal) is configured with the gateway’s URL, its traffic is governed, metered, and audited. Brutor does not — and does not claim to — govern what employees do inside the consumer ChatGPT or Claude apps themselves; that is the domain of network controls and the vendors’ own admin consoles. (Brutor can import vendor admin telemetry for cross-vendor cost observability.)

Where to next

If the gateway isn’t running yet, start with the Quickstart — Docker Compose, about ten minutes. Then make your first governed LLM call and watch it appear in Mission Control.