Authentication

Mosaic's MCP server supports two ways to authenticate a remote request: OAuth 2.1 (for claude.ai, Claude Science, Cowork, Claude Desktop/Code as a custom connector — sign in, no key to copy) on the Streamable-HTTP /mcp endpoint, and a static API key Bearer token on the legacy SSE /sse endpoint (for clients that don't do the OAuth dance, e.g. Cursor, scripts). Local stdio dev is single-user and uses env vars instead — see Local development. Full design: docs/decisions/mcp-oauth.md.

Connecting a Claude client (OAuth, recommended)

Add Mosaic as a custom connector:

• claude.ai: Settings → Connectors → Add custom connector → URL https://mcp.getmosaic.dev/mcp → follow the sign-in prompt (enter your email, click the link Mosaic emails you, approve access).
• Claude Desktop / Code / Cowork: same URL, added wherever that client exposes custom connectors; it will open the same sign-in flow in your browser.

No key to generate or paste — you sign in with the same email you'd use on the web app (a magic-link email, not a password). Free-tier tools work immediately after connecting; Pro-only tools unlock the moment your account's plan does, no reconnect required. Access + refresh tokens are issued and rotated automatically by your Claude client; there's nothing to manage on /account/keys for this path.

API keys (for clients that only support a static Bearer token)

• Format: mk_live_… (production) or mk_test_… (Dodo test mode).
• Issued from Account → API keys (/account/keys) and shown once at creation — copy it immediately; only a hash is stored.
• A key is identified in the UI by its prefix, e.g. mk_live_ab3d….
• Multiple named keys per account ("laptop", "ci", "cursor"). Revoke or rotate any of them independently.

Sending the key

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Invalid, missing, or revoked keys return 401. Requests over your plan quota return 429 (the limit and reset are in the response).

Per-client setup (API key, /sse)

Claude Desktop / Claude Code — claude_desktop_config.json (prefer the OAuth connector above if your client supports custom connectors — this static-key form still works for older configs):

{
  "mcpServers": {
    "mosaic": {
      "url": "https://mcp.getmosaic.dev/sse",
      "headers": { "Authorization": "Bearer mk_live_xxxx" }
    }
  }
}

Cursor — Settings → MCP → Add server: URL https://mcp.getmosaic.dev/sse, header Authorization: Bearer mk_live_xxxx.

Rotating & revoking

• Rotate: issues a new key and immediately revokes the old one. Update your client config with the new key.
• Revoke: disables a key at once. Idempotent.
• There is no automatic expiry.

Quotas by plan

Team (Lab) keys meter against the shared team subscription, not the individual member.

Local development

The stdio transport (running the server on your own machine) is single-user and does not use Bearer auth. Set MOSAIC_TIER (or MOSAIC_API_KEY) in the environment for local tier selection. This path is dev-only and is not available on the hosted server.

Legacy X-API-Key (deprecated)

The old X-API-Key header is still accepted for a short transition window and will be removed when Move 2 ships. Migrate to Authorization: Bearer.