[view as .md]

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:

  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 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:
{
  "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 for the list.

For low-level OAuth endpoints and metadata URLs, see the OAuth reference.