Wire up the Litmus MCP server with Clerk OAuth or an API key from Claude Code, Claude Desktop, Cursor, or a custom client.

Authentication

Litmus accepts two bearer-token shapes: Clerk OAuth for interactive clients (Claude Desktop, Claude Code, Cursor) and API keys for headless agents and CI. Both resolve to the same Clerk org — pick whichever fits the calling context.

Use your org-scoped URL. Each Litmus org has its own MCP connector URL of the form https://litmushiring.com/mcp/<your-org-id>/ — copy the exact value from Settings → API Keys in your dashboard. The org-scoped path is required if you're a member of multiple Clerk orgs (the OAuth verifier needs to know which one you mean), and recommended in all cases. The trailing / matters too — without it, most HTTP clients drop the Authorization header across a 308 redirect and you'll see a confusing 401.

The legacy https://litmushiring.com/mcp/ (no org segment) still works for API-key callers (each key is org-scoped by construction) and for OAuth users who belong to exactly one Clerk org. Examples below use the org-scoped form throughout — substitute your own org id.

OAuth

Modern MCP clients discover Litmus's OAuth flow automatically. Point the client at https://litmushiring.com/mcp/<your-org-id>/ and on first call it'll open a browser for Clerk sign-in, get a scoped token, and reuse it for subsequent requests.

OAuth access is admin-only — non-admin members of your Clerk org get a 401 even after a successful sign-in.

Claude Code

bash

claude mcp add --transport http litmus https://litmushiring.com/mcp/<your-org-id>/

Verify with /mcp inside a Claude Code session.

Claude Desktop

Open Settings → Connectors → Add custom connector, paste https://litmushiring.com/mcp/<your-org-id>/, and follow the Clerk sign-in popup. No config file edit needed.

Cursor

Add to your mcp.json:

json

{
  "mcpServers": {
    "litmus": {
      "type": "http",
      "url": "https://litmushiring.com/mcp/<your-org-id>/"
    }
  }
}

Cursor runs the OAuth flow on first use.

API keys

OAuth covers any client a human signs into. API keys cover the rest: CI runners, cron jobs, backend services, and one-off scripts where opening a browser isn't an option. Unlike OAuth tokens, API keys don't expire — they're valid until you revoke them.

Mint a key

API key minting is admin-only — non-admin members of your Clerk org won't see the Settings → API Keys tab, and direct API hits to mint or revoke a key return 403.

In your dashboard, go to Settings → API Keys → Create key, name it, and copy the value — Litmus only shows it once. Revoke anytime from the same page; revocation takes effect on the next request.

Direct bearer (Python / TypeScript / your own agent)

Set the Authorization header on the connection:

python

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": "Bearer litmus_sk_..."}
    async with streamablehttp_client(
        "https://litmushiring.com/mcp/<your-org-id>/", headers=headers
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            for t in tools.tools:
                print(t.name)

asyncio.run(main())

The same header works for the artifact streaming URLs returned by get_submission — one credential covers the whole surface.

Claude Code (headless / CI)

For service-account use where you don't want OAuth's browser step:

bash

claude mcp add --transport http litmus https://litmushiring.com/mcp/<your-org-id>/ \
  --header "Authorization: Bearer litmus_sk_..."

Pass --scope project to write a shared .mcp.json (reference the token via ${LITMUS_MCP_TOKEN} so the secret isn't committed).

Audit log

Every MCP tool call your org's credentials make — OAuth or API key — lands in Settings → Audit Log. Each row records the tool name, status (ok or the exception class), latency, and which credential made the call (API key name + prefix, or the OAuth user). The page is admin-only, paginated, and shows revoked keys with a Revoked badge so post-revocation activity stays attributable.

Use it to spot credentials that should be rotated, confirm what an agent actually did, or surface unusual access patterns. Activity appears within a second of the call landing.

Older clients

Anything that doesn't speak HTTP MCP natively used to need the mcp-remote stdio-to-HTTP bridge. We don't recommend it. CVE-2025-6514 (command injection, CVSS 9.6) lets a malicious MCP server run arbitrary commands on the user's machine. Upgrade to a client version with native HTTP MCP support instead.

Rate limits

The MCP surface is rate-limited per-org, defaulting to 60 requests per minute. All API keys on an org share one bucket, and artifact streaming URLs count against it too — minting more keys won't buy more headroom.

When you exceed the limit you'll get a 429 with a Retry-After header; see Troubleshooting → 429 Too Many Requests for the response shape and a backoff snippet. If your workload needs a higher ceiling, email founders@litmushiring.com.