Authentication

Multiplist exposes two surfaces, and they take different credentials. Picking the wrong one is the most common cause of 401s, so the rule is simple:

API Keys and MCP Tokens live in separate tables with different formats. An mp_live_ key will never validate on /mcp, and an MCP token will never validate on /api/v1/*. They are not interchangeable.

# API Keys (for the REST API)

For headless integrations that call the REST API directly — webhooks, cron jobs, server-to-server pipelines.

• Generate in Settings → API Keys inside the Multiplist app.
• Format: mp_live_ + 32 alphanumeric characters (40 chars total).
• Storage: SHA-256 hashed at rest. The raw key is shown once at creation — store it in a secrets manager.
• Header: Authorization: Bearer mp_live_…
• Scopes (granted at key creation): extract, read, synthesize.
• Endpoints: see the API Reference — POST /api/v1/extract, GET /api/v1/seeds/:sourceId, POST /api/v1/synthesize, POST /api/v1/batch/extract, etc.

curl https://multiplist.ai/api/v1/seeds/SOURCE_ID \
  -H "Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# MCP Tokens (for the MCP endpoint)

For MCP clients that need to call Multiplist as a set of tools — local stdio bridges, CI scripts, agent frameworks. If your client speaks the OAuth 2.1 flow (Claude Desktop, ChatGPT), use OAuth instead — see below.

• Generate in Settings → MCP Tokens inside the Multiplist app.
• Format: mcp_live_ + 64 hex characters (73 chars total). The mcp_live_ prefix distinguishes these at a glance from REST API Keys (mp_live_).
• Legacy tokens: tokens issued before May 2026 are 64-char hex with no prefix. They remain valid — the server hashes whatever is sent and looks it up. No need to rotate unless you want to.
• Storage: SHA-256 hashed at rest. The raw token is shown once at creation.
• Header: x-mcp-key: <token> — not Authorization: Bearer.
• Scopes (granted at token creation): seeds:read, seeds:write, sources:read, sources:write, vault:read, vault:write, extract:run, recall:search, skills:read, skills:write, workspace:read, workspace:write, and more.

curl https://multiplist.ai/mcp \
  -H "x-mcp-key: mcp_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "tools/list", "id": 1 }'

The @multiplist/mcp-server npm bridge reads the token from the MULTIPLIST_MCP_TOKEN env var (preferred), or the legacy aliases MULTIPLIST_API_KEY / MCP_KEY, and forwards it as x-mcp-key automatically.

# OAuth 2.1 with PKCE (for hosted MCP clients)

The easiest option for Claude Desktop, ChatGPT, and any MCP client that speaks StreamableHTTP with OAuth.

1. Configure the client with https://multiplist.ai/mcp.
2. On first use, the client opens the Multiplist login page in your browser.
3. Approve the connection — the access token is stored in the client and refreshed automatically.
4. No tokens to copy or rotate.

OAuth access tokens are sent as Authorization: Bearer … to /mcp and are validated through the OAuth flow, separately from MCP Tokens.

# Common 401 causes

If you're getting 401 INVALID_API_KEY or Authentication required:

1. Wrong token type for the endpoint. This is the #1 cause. API Keys (mp_live_…) only work on /api/v1/*. MCP Tokens (mcp_live_…, or 64-char hex for legacy tokens) only work on /mcp. Check the table at the top of this page.
2. Wrong header for the endpoint. REST API uses Authorization: Bearer. MCP static tokens use x-mcp-key. Don't mix them.
3. Token revoked. Check the active list in the corresponding settings page.
4. Trailing whitespace / quotes on a pasted token. The middleware tolerates these as of May 2026, but older deployments may not.

The REST API's 401 response now includes details.keyPrefix showing the first 16 characters the server actually saw — useful for confirming the token reached the server intact.