<!-- source: https://modelux.ai/docs/guides/mcp-setup -->

> Manage modelux from Claude Code, Cursor, or any MCP client.

# Connecting your AI (MCP)

modelux exposes every management action as a tool through the Model Context
Protocol (MCP). Connect an MCP-aware AI client — Claude Desktop, Claude Code,
ChatGPT, Cursor — and you can manage routing, budgets, providers, analytics,
and more through natural language.

There are two ways to connect:

- **OAuth (recommended).** Paste a single URL, click "Allow," done. Best for
  desktop and editor clients that can open a browser.
- **Management API key.** Bearer token on every request. Best for CI, scripts,
  and headless clients that can't drive a browser flow.

## Connect via OAuth

For any MCP client that speaks the
[MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization):

1. Add a new MCP server and paste the URL:

   ```
   https://api.modelux.ai/api/mcp
   ```

2. The client will:
   - Fetch `/.well-known/oauth-protected-resource` to discover modelux's
     authorization server.
   - Register itself (via [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)
     dynamic client registration) if it isn't pre-registered.
   - Open a browser to
     `https://api.modelux.ai/api/oauth/authorize` with a PKCE
     challenge.

3. Sign in to modelux, review the requested scopes (`mcp:read`, `mcp:write`),
   and click **Allow**. The browser redirects back to the client; the client
   exchanges the authorization code for an access token at
   `/api/oauth/token` and starts calling tools.

Review and revoke individual connections any time from
**Settings → Connected apps**.

## Connect with a management API key

For CI, scripts, or MCP clients that can't drive a browser flow:

1. In the dashboard, go to **Settings → API & MCP**.
2. Create a **management API key** (`mlx_mgmt_*`). Copy it — it's only shown
   once.
3. Paste the MCP config into your client:

```json
{
  "mcpServers": {
    "modelux": {
      "url": "https://api.modelux.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer mlx_mgmt_..."
      }
    }
  }
}
```

Restart the client. It will connect and list available tools.

Management API keys are org-scoped: whoever holds the key can perform any
management action within that org, so treat them like any privileged
credential — don't commit them to source control, rotate periodically, and
revoke immediately if exposed. For per-user, revocable, least-privilege
access, prefer OAuth.

## What you can ask

- "Create a cascade that tries haiku first then falls back to sonnet"
- "Show me yesterday's spend by model"
- "Set a $500/month cap on my production project with auto-downgrade to @cheap"
- "Which provider had the highest error rate last week?"
- "Rotate my OpenAI API key and verify it works"
- "Replay the last 24 hours of traffic against the candidate config"

## Scopes

OAuth tokens carry one or both of:

- `mcp:read` — list / get / describe tools only.
- `mcp:write` — required for any mutating tool (create, update, delete,
  revoke, …). A token with only `mcp:read` hitting a write tool gets an
  `insufficient_scope` 403.

Scope narrows what a token can do, but your dashboard role still gates the
underlying action: a user with `member` role can't grant a token `admin`
powers by requesting `mcp:write`.

## Tools available

modelux exposes 80+ tools covering the full management API surface:
projects, routing configs, providers, budgets, API keys, analytics,
audit logs, webhooks, experiments, and org/member management. See the
[full management reference](/docs/api/management) for the list.

For low-level OAuth endpoints and metadata URLs, see the
[OAuth reference](/docs/api/oauth).