Advanced Authentication

The default browser-based OAuth flow covers most setups. Use this page when you need machine credentials (automation, CI, non-interactive agents) or when your client only supports stdio transport.

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.

Getting credentials

Generate OAuth client credentials for your tenant at:

https://auth.causely.app/oauth/portal/api-tokens

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

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:

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.