# bifrost-mcp

An MCP (Model Context Protocol) server for managing a [Bifrost](https://github.com/maximhq/bifrost)
LLM gateway's admin API — governance (virtual keys, teams, customers, budgets), provider
configuration, routing rules, model/pricing config, request-log observability, and core gateway
config.

This is not the MCP-gateway feature built into Bifrost itself (routing MCP tool calls to LLMs). It's
the other direction: it lets an MCP client (Claude Code, Codex, etc.) *administer* your Bifrost
instance — create a virtual key for a new environment, set budgets, add provider API keys, and so on
— without leaving your agent session.

## Setup

```bash
npm install
npm run build
```

### Authentication

Bifrost's `/api/*` management endpoints accept a Bearer token that is either:

- a session token from `POST /api/session/login`, or
- `base64("admin_username:admin_password")` — the same admin account you create once via
  `BIFROST_SETUP_TOKEN` when you first set up the instance.

Set one of these in your environment:

| Variable | Description |
|---|---|
| `BIFROST_URL` | Base URL of your Bifrost instance, e.g. `https://bf.example.com`. Required. |
| `BIFROST_ADMIN_USERNAME` + `BIFROST_ADMIN_PASSWORD` | Admin credentials created in the Bifrost dashboard. |
| `BIFROST_MANAGEMENT_TOKEN` | A pre-obtained Bearer token, if you have one, instead of the two above. |

## Usage with an MCP client

Add it to your client's MCP config, e.g. `.mcp.json` for Claude Code:

```json
{
  "mcpServers": {
    "bifrost": {
      "command": "node",
      "args": ["/path/to/bifrost-mcp/dist/index.js"],
      "env": {
        "BIFROST_URL": "https://bf.example.com",
        "BIFROST_ADMIN_USERNAME": "admin",
        "BIFROST_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}
```

## Tools

**Virtual keys** — `bifrost_list_virtual_keys`, `bifrost_get_virtual_key`, `bifrost_create_virtual_key`,
`bifrost_update_virtual_key`, `bifrost_delete_virtual_key`, `bifrost_rotate_virtual_key`,
`bifrost_get_virtual_key_quota`

**Teams** — `bifrost_list_teams`, `bifrost_get_team`, `bifrost_create_team`, `bifrost_update_team`,
`bifrost_delete_team`

**Customers** — `bifrost_list_customers`, `bifrost_get_customer`, `bifrost_create_customer`,
`bifrost_update_customer`, `bifrost_delete_customer`

**Providers** — `bifrost_list_providers`, `bifrost_get_provider`, `bifrost_add_provider`,
`bifrost_delete_provider`, `bifrost_list_provider_keys`, `bifrost_add_provider_key`,
`bifrost_delete_provider_key`

**Routing rules** — `bifrost_list_routing_rules`, `bifrost_get_routing_rule`,
`bifrost_create_routing_rule`, `bifrost_update_routing_rule`, `bifrost_delete_routing_rule`,
`bifrost_get_complexity_analyzer_config`, `bifrost_update_complexity_analyzer_config`

**Budgets & rate limits** (read-only aggregate views; create/update happens on the owning
virtual key/team/customer/model-config) — `bifrost_list_budgets`, `bifrost_list_rate_limits`

**Model configs** (per-model budget/rate-limit overrides) — `bifrost_list_model_configs`,
`bifrost_get_model_config`, `bifrost_create_model_config`, `bifrost_update_model_config`,
`bifrost_delete_model_config`

**Pricing overrides** — `bifrost_list_pricing_overrides`, `bifrost_create_pricing_override`,
`bifrost_update_pricing_override`, `bifrost_delete_pricing_override`, `bifrost_force_sync_pricing`

**Model catalog** — `bifrost_list_models`, `bifrost_list_base_models`, `bifrost_get_model_details`,
`bifrost_get_model_parameters`

**Observability** — `bifrost_list_request_logs`, `bifrost_get_request_log`, `bifrost_get_log_stats`,
`bifrost_get_log_dashboard`, `bifrost_get_log_histogram`, `bifrost_get_log_rankings`

**Gateway config** — `bifrost_get_config`, `bifrost_update_config`, `bifrost_get_proxy_config`,
`bifrost_update_proxy_config`, `bifrost_get_version`, `bifrost_list_notifications`,
`bifrost_clear_cache_entry`, `bifrost_clear_cache`

This covers Bifrost's governance hierarchy (Customer → Team → Virtual Key → Provider Config),
provider/key management, routing rules, model/pricing config, request-log observability, and core
gateway config. **Not covered**, because these are Enterprise-only features not present in the
open-source build: RBAC, access-profiles, business units, audit-log export, the legacy `/api/teams`
`/api/users` `/api/roles` `/api/access-profiles` `/api/audit-logs` `/api/business-units` paths (all
superseded by `/api/governance/*` anyway). Also not covered: Bifrost's own MCP-gateway feature
(`/api/mcp/*`, `/api/mcp-logs/*` — routing MCP tool calls to LLMs, unrelated to administering
Bifrost itself), webhooks, plugins, circuit-breaker policies, prompt-repo, and skills. Open an issue
or PR if you need any of these.

## Development

```bash
npm run dev    # run directly with tsx, no build step
npm run lint
```

## License

MIT