Your API key:

All requests below will use this key. Your API key is sent directly to api.cueapi.ai and never stored by the docs site.

POST/v1/auth/mcp-exchange

MCP Token Exchange

Exchange a one-time session token + approved client_id for a fresh, scoped, never-stored API key. Used by MCP hosts (Claude.ai Custom Connectors, Cursor, etc.).

MCP hosts (Claude.ai Custom Connectors, Cursor, Zed, etc.) call this endpoint to mint a per-connection API key after a user finishes the device-code login flow. The result is scoped, audited, and labeled as mcp:{client_id}:{user-label}.

Note

No bearer auth required. The session_token is the credential and is single-use — consumed on exchange, like POST /v1/auth/session.

Flow

The MCP host kicks off device-code auth via POST /v1/auth/device-code.
The user approves login at the verification URL.
The MCP host polls POST /v1/auth/device-code/poll and receives a session_token.
The MCP host calls this endpoint with the session_token + its registered client_id. A fresh API key is minted, returned once in plaintext, and stored hashed.

The plaintext is never retrievable afterward — MCP-exchanged keys intentionally bypass the Reveal Key flow.

Request

bash

curl -X POST https://api.cueapi.ai/v1/auth/mcp-exchange \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "stk_a1b2c3d4e5f6…",
    "client_id": "claude-ai-web-prod",
    "label": "Claude Desktop on Govind'\''s Mac"
  }'

Response

json

{
  "api_key": "cue_sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "user_id": "u_a1b2c3",
  "key_id": "6e8fc3a0-7a12-4f8a-b8b6-9c5e1d2a3b4c",
  "expires_at": null
}

Request body

Field	Type	Description
`session_token`	string (8–256)	One-time token from device-code flow. Consumed on success.
`client_id`	string (1–128)	Registered MCP client identifier. Must be in `ALLOWED_MCP_CLIENT_IDS` on this deployment.
`label`	string (1–80, default `"mcp-connection"`)	Human-readable label used in dashboards and audit log. Stored as `mcp:{client_id}:{label}` (truncated to 100 chars total).

Errors

Status	Code	Cause
401	`invalid_token`	Session token is invalid, expired, or already consumed
401	`user_not_found`	Session token references a deleted account
403	`mcp_exchange_disabled`	Deployment has no `ALLOWED_MCP_CLIENT_IDS` configured (endpoint disabled)
403	`invalid_client_id`	`client_id` is not in the deployment's allow-list
429	`rate_limited`	Per-user MCP exchange rate limit hit (matches `POST /v1/auth/keys` budget)

Differences vs `POST /v1/auth/keys`

	`keys`	`mcp-exchange`
Auth	Bearer	None (token is the credential)
Plaintext retrievable later?	Yes (via `GET /v1/auth/key/{id}/reveal`)	No — never stored encrypted
Label format	Free	`mcp:{client_id}:{label}` enforced
`created_by`	`user`	`mcp-exchange`
Client allow-list?	No	Yes (`ALLOWED_MCP_CLIENT_IDS`)

POST/v1/auth/mcp-exchange

Try it

Request Body

Enter your API key above to send requests

Previous← Refresh Session NextCurrent User →