Advanced Authentication

The default browser-based OAuth flow covers most interactive setups. Use this page when you need credentials that skip the browser (personal tokens or tenant-wide API tokens), or when your client only supports stdio.

If you are connecting Claude Code, start with claude mcp add on the Claude Code page. Custom Claude.ai / Claude Desktop connectors are a separate path and are not available on every Claude plan. See Claude Desktop.

Which credential to use

MCP accepts two kinds of client credentials. Both are a client_id and client_secret that the server exchanges for an access token. What you can query is the same either way; the difference is who the request runs as.

Credential	Use when	Identity	Create
Personal token	You are connecting an agent that should use your access	Inherits your user permissions	Personal tokens
Tenant-wide API token	A team or background agent should not be bound to one person's identity	Role you assign on the token	API tokens

Browser SSO is the default for Claude Code, Claude Desktop, Cursor, and similar clients. It is convenient for a one-off session, but access tokens expire after a few hours and the client prompts you to sign in again. A personal or tenant-wide token lasts until the expiry you set when you create it.

See API Tokens for how to create and rotate tokens.

Client ID and Client Secret

For non-interactive MCP calls, supply client credentials that the server exchanges for a Frontegg access token. The HTTP Basic username is always client_id and the password is always client_secret.

Encoding

Concatenate client_id, a single colon (:), and client_secret, no newline, no extra characters, then Base64-encode the result:

printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 -w 0

Use the single line of output as the Base64 payload.

How to send it

Method	When to use
Authorization: Basic <Base64(client_id:secret)>	Requests with no Authorization: Bearer token, typical for curl or custom HTTP clients
X-Causely-Client-Basic	Same Base64 payload (with or without the Basic prefix). Use when an MCP proxy reserves or rewrites Authorization. If both headers are present, the server prefers X-Causely-Client-Basic.

If the request already includes a non-empty Authorization: Bearer token, the server validates that JWT and ignores client credentials entirely.

Adding credentials to a client config

For native HTTP MCP clients, add a headers object alongside url. Examples for each config format:

Claude Code CLI, with a personal or tenant-wide token (no browser prompt):

claude mcp add --scope user --transport http causely https://api.causely.app/mcp \
  --header "X-Causely-Client-Basic: Basic ${CAUSELY_MCP_CLIENT_BASIC}"

Set CAUSELY_MCP_CLIENT_BASIC to the Base64 string without the Basic prefix; the snippet adds the prefix. Omit --header to use browser OAuth instead. See Claude Code.

JSON mcpServers (Claude Code, Cursor):

{
  "mcpServers": {
    "causely": {
      "type": "http",
      "url": "https://api.causely.app/mcp",
      "headers": {
        "X-Causely-Client-Basic": "Basic <Base64(client_id:secret)>"
      }
    }
  }
}

JSON servers (VS Code / GitHub Copilot):

{
  "servers": {
    "causely": {
      "type": "http",
      "url": "https://api.causely.app/mcp",
      "headers": {
        "X-Causely-Client-Basic": "Basic <Base64(client_id:secret)>"
      }
    }
  }
}

TOML (Codex), use env_http_headers to read the value from an environment variable at runtime so secrets stay out of the file:

[mcp_servers.causely]
url = "https://api.causely.app/mcp"
enabled = true

[mcp_servers.causely.env_http_headers]
"X-Causely-Client-Basic" = "CAUSELY_MCP_CLIENT_BASIC"

Export CAUSELY_MCP_CLIENT_BASIC to the Base64 string (without a Basic prefix, Codex does not prepend it for you unless you include it in the variable value).

caution

Do not commit real secrets to source control. Use your tool's secret or input-variable mechanism where available, for example VS Code MCP inputs and ${input:…} in headers.

Stdio Fallback (mcp-remote)

If your client cannot use streamable HTTP to https://api.causely.app/mcp, run mcp-remote as a local stdio bridge: your tool launches Node locally; mcp-remote handles OAuth and forwards MCP traffic over HTTP to Causely. Requires Node.js and npx on your PATH.

Browser OAuth (default for this path):

{
  "mcpServers": {
    "causely": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.causely.app/mcp/"]
    }
  }
}

Machine credentials: mcp-remote accepts repeated --header "Name: value" flags and expands ${ENV_VAR} inside header values:

{
  "mcpServers": {
    "causely": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.causely.app/mcp/",
        "--header",
        "X-Causely-Client-Basic: Basic ${CAUSELY_MCP_CLIENT_BASIC}"
      ]
    }
  }
}

Set CAUSELY_MCP_CLIENT_BASIC to the Base64 string without the Basic prefix, the snippet above adds the prefix in the header string.