Connect any compatible remote MCP client to Litmus with OAuth, or use a scoped API key for headless automation.

Authentication

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

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. Authentication and permissions are separate: the OAuth application also grants the same fine-grained capabilities listed for API keys below. A connection can use only tools covered by its granted scopes; mcp:tools is only the transport marker and does not grant access to every tool.

Some clients request scopes explicitly and others rely on the OAuth application's default scopes. Litmus publishes the full supported set in its protected-resource metadata so either style works. Changing an application's grants requires reconnecting it so Clerk can issue a new token. A connection made before these permissions existed keeps access to every tool until it reconnects.

Litmus uses remote Streamable HTTP MCP plus OAuth dynamic client registration and PKCE S256. That is the same portable connection contract used by Greenhouse MCP. It is not tied to a Claude plugin: use the org-scoped URL in ChatGPT, Claude, Cursor, Google Antigravity, Glean, Microsoft Copilot Studio, Amazon Q, Grok, or another client that supports that contract. Some enterprise clients require an administrator to add the remote MCP server before users can sign in.

Claude Code

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:

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

Cursor runs the OAuth flow on first use.

ChatGPT and other hosted clients

Create a custom MCP app/connector and paste https://litmushiring.com/mcp/<your-org-id>/ as the server URL. Choose OAuth when the client asks for authentication; it discovers Litmus's authorization and registration endpoints automatically. Do not choose a custom API-key field for ChatGPT — use OAuth there. For enterprise-managed tools such as Copilot Studio, Glean, Amazon Q, or Antigravity, an administrator may need to publish the connection after completing the same OAuth sign-in.

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.

Tick the permissions the client needs, or Full access. The same permissions govern the REST API and the MCP server, so one key covers both. Authentication & scopes lists every permission. Each tool needs one permission (listed on the tool reference); a tool the key lacks it for fails with an error naming the permission, and every other tool keeps working. OAuth connections use those same permissions, configured as custom scopes on their Clerk OAuth application.

Direct bearer (Python / TypeScript / your own agent)

Set the Authorization header on the connection:

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:

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), and every REST API request, lands in Settings → Audit Log, in one list. Each row records whether it was MCP or the API, the tool or endpoint, the status (ok, the HTTP status, or the exception class; a call the key lacked the permission for reads missing permission), latency, and which credential made it (API key name + prefix, or the OAuth user). Filter to one key to see everything it did across both. 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 support@litmushiring.com.