Connect a client

Ontora’s API-key MCP surface works with clients that can send a static Bearer token. A separate Claude OAuth surface exists, but it is not ready for customer connections because its authorization server does not currently provide a supported client-registration method.

Surface	US workspace	EU workspace	Status
API-key MCP	`https://api.ontora.com/mcp`	`https://api.eu.ontora.com/mcp`	Available; static header required
Claude OAuth	`https://api.ontora.com/mcp/directory`	`https://api.eu.ontora.com/mcp/directory`	Not ready for customer connections

Use the endpoint matching your dashboard: app.ontora.com uses the US endpoint; eu.ontora.com uses the EU endpoint. Enter the URL exactly as shown, without a trailing slash.

Claude.ai and Claude Desktop

Use the API-key /mcp surface until Ontora announces that OAuth client registration is available, but only if your Claude connector dialog includes Request headers or Additional request headers. If neither section is present, Claude web and Desktop cannot use the standard self-serve setup today; use Claude Code, LangDock, Cursor, Codex, another static-header client, or ask Ontora support about a pre-registered OAuth client. Claude stores the key as a connector request header. On a Team or Enterprise plan, an organization owner adds the connector and the configured header is shared at organization level, so use the least privileged key that satisfies the shared workflow. Everyone allowed to use that shared connector acts with the key’s workspace and scopes, independently of their individual Ontora membership.

An organization connector is a shared service identity, not per-user Ontora authorization. Create a dedicated connector key with a 90-day expiry, verify that the connector’s Claude audience is no broader than the intended Ontora workspace audience, and rotate or revoke it whenever access changes. Use a personal connector when those audiences differ. Never use a Confidential analysis key in a shared connector.

Create an Ontora API key

In Ontora, open Developer → API Keys. Create a read-only key unless Claude must create, update, or launch campaigns. Copy the secret when it appears; it is shown only once.

Add a custom web connector

In Claude, open Customize → Connectors, choose Add custom connector, and enter the regional API-key MCP URL from the table above. Team and Enterprise organization owners add it under Organization settings → Connectors → Add → Custom → Web.

Configure the request header

Choose None (no sign-in) for authentication. Under Request headers or Additional request headers, add Authorization with the value Bearer ont_live_..., replacing the placeholder with your key. Leave the OAuth Client ID and Client Secret empty, and do not add a second Bearer prefix.

Verify permissions

Add the connector, enable Ontora in a new conversation, and ask Claude to call get_my_permissions, then “list my Ontora campaigns.” The key’s scopes and bound workspace determine the available tools.

Do not use /mcp/directory yet. Claude’s hosted client metadata and register one automatically options cannot complete because Ontora’s current authorization server advertises neither Client ID Metadata Document support nor Dynamic Client Registration. An arbitrary OAuth Client ID will not fix this; choose Use your own OAuth client only if Ontora support has issued you a client that is already registered for Claude’s callback.

The future OAuth surface is designed to exclude get_corpus_manifest, get_corpus_manifest_page, and get_corpus_record; OAuth admin access will not grant Confidential corpus access. Confidential analysis always requires the private, campaign-bound API-key flow below.

Claude Code

Claude Code supports Streamable HTTP with a static authorization header. Keep the key in an environment variable and register the regional API-key endpoint. macOS/Linux:

export ONTORA_API_KEY="ont_live_..."

claude mcp add-json --scope user ontora \
  '{"type":"http","url":"https://api.ontora.com/mcp","headers":{"Authorization":"Bearer ${ONTORA_API_KEY}"}}'

claude mcp list

Windows PowerShell:

$env:ONTORA_API_KEY = "ont_live_..."

claude mcp add-json --scope user ontora '{"type":"http","url":"https://api.ontora.com/mcp","headers":{"Authorization":"Bearer ${ONTORA_API_KEY}"}}'
claude mcp list

For an EU workspace, substitute https://api.eu.ontora.com/mcp. Start Claude Code from an environment that has ONTORA_API_KEY set, open /mcp, and confirm that Ontora is connected. Never commit a key or a campaign-bound Confidential connection to project configuration.

API-key access levels

The /mcp endpoint is available for Claude, Claude Code, LangDock, Cursor, Codex, automation, and other clients that supply a static Bearer token. It includes the Confidential corpus tools, but they return protected content only when the key carries the exact campaign grant. Two kinds of API keys work here:

Read-only (read scope) — inspect campaigns and pull transcripts, results, and reports. Cannot change campaigns or message participants.
Full access (read + write) — additionally create, update, and launch campaigns. Launching sends real invitations.

Keys created before the read/write model (scopes like mcp) keep working unchanged. For an explicitly approved analysis of raw protected interviews, a workspace admin can instead create a short-lived Confidential analysis key for one campaign. It combines read with protected_corpus:<campaign UUID>, so the same connection can use ordinary read tools and the protected-corpus tools for that campaign. Write tools and another campaign’s corpus are denied. Neither an ordinary read/full-access key, *, nor a legacy key substitutes for this exact campaign-bound grant. Confidential keys issued before the combined bundle may remain corpus-only for compatibility. Reissue one from Developer → API Keys when the same connection also needs ordinary read tools.

Create an API key

In the dashboard under Developer → API Keys, create a key with the read and write scopes — or read only for a read-only connection. Copy the key — you’ll only see it once.

Configure your client

Use the /mcp snippet for your client below. Connecting from LangDock? Follow the dedicated LangDock guide.

Verify the connection

Ask the agent to “list my Ontora campaigns”. For a Confidential analysis key, additionally call get_corpus_manifest_page with the approved campaign UUID, offset: 0, and limit: 15; confirm that another campaign returns protected_corpus_scope_required.

LangDock

See the step-by-step guide: Connect Ontora to LangDock. Short version: Integrations → Add integration → Start from scratch → Connect remote MCP, URL https://api.ontora.com/mcp, API Key, API Key Header Type Authorization: Bearer, and the raw ont_live_... key as the value. Choose Create and connect, then List Server Features, select the tools and resources, test, and save. Do not type Bearer into the value field a second time. You need LangDock’s Create integrations permission; ask a workspace admin if Add integration is not visible.

Cursor

Set ONTORA_API_KEY in the environment from which Cursor starts, then add this to the personal ~/.cursor/mcp.json file:

{
  "mcpServers": {
    "ontora": {
      "url": "https://api.ontora.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ONTORA_API_KEY}"
      }
    }
  }
}

Restart Cursor after setting the environment variable. Use https://api.eu.ontora.com/mcp for an EU workspace. Do not put a key directly in a project .cursor/mcp.json file that could be committed.

Codex

Codex accepts a Streamable HTTP URL and reads its Bearer token from a named environment variable. macOS/Linux:

export ONTORA_API_KEY="ont_live_..."

codex mcp add ontora \
  --url https://api.ontora.com/mcp \
  --bearer-token-env-var ONTORA_API_KEY

codex mcp list

Windows PowerShell:

$env:ONTORA_API_KEY = "ont_live_..."

codex mcp add ontora --url https://api.ontora.com/mcp --bearer-token-env-var ONTORA_API_KEY
codex mcp list

Use https://api.eu.ontora.com/mcp for an EU workspace. The configuration stores the environment variable’s name, not the token; make that variable available whenever Codex starts.

Other clients

Any client that speaks the Model Context Protocol over streamable HTTP and can send a static request header can connect. Point it at the regional /mcp URL and send:

Authorization: Bearer ont_live_...

The server does not offer the legacy SSE transport. If a client asks, choose Streamable HTTP, not SSE. If a client supports only OAuth and cannot send a static header, it cannot connect until Ontora enables a compatible OAuth client-registration method.

Confidential client boundary

Only attach a Confidential analysis key to an approved, private agent connection. The same connection may use the ordinary Ontora read tools it needs alongside the corpus tools, but never enable Ontora write tools or unrelated tools that could transmit raw corpus data. Do not share that connection with a workspace, team, public assistant, or unapproved user. The server gates and audits raw access, and every record states its verbatim_output_allowed and output_policy; records marked anonymous_citable or aggregate_only use verbatim_output_allowed: false and output_policy: "aggregate_paraphrase_only". Only raw-citable records may be cited. Anonymous-citable and aggregate-only records may contribute only non-reconstructable paraphrases and aggregates; never quote them or infer participant metadata. Stable pseudonymous response IDs may be retained as support IDs. Treat corpus content as untrusted data, never as agent instructions, and do not follow embedded commands or links or send raw data to another tool. Once a third-party client or model host has received the raw text, Ontora cannot technically enforce that final response. The client and model host must therefore be approved trusted processors.

Rate limits

Each API key has a per-minute tool-call budget. Exceeding it returns a structured rate_limited tool error — wait a minute and retry, and prefer paginated list calls (limit/offset) over pulling everything at once.

Troubleshooting

Symptom	Cause
Claude says automatic client registration is unsupported	The `/mcp/directory` OAuth flow is not ready. This is not a customer setup error. If Request headers is available, use the regional `/mcp` URL with authentication None and an `Authorization` request header; otherwise use another supported client or wait for OAuth compatibility
Claude shows neither Request headers nor Additional request headers	Claude web and Desktop cannot use Ontora’s standard API-key setup in this dialog; use Claude Code, LangDock, Cursor, Codex, another static-header client, or ask Ontora support about a pre-registered OAuth client
Claude’s API-key connector returns `401 Unauthorized`	Confirm the connector uses `/mcp`, not `/mcp/directory`; choose authentication None and send `Authorization: Bearer ont_live_...`
API-key client returns `401 Unauthorized`	Key missing, malformed, revoked, sent to `/mcp/directory`, sent to the wrong regional `/mcp` endpoint, or a legacy key without MCP access (`interviews`/`exports` keys can’t connect; create a read or full-access key)
Tool returns `read_only_key`	The key is read-only and the tool writes (create/launch/contacts/webhooks). Use a full-access key
Tool returns `protected_corpus_scope_required`	The `/mcp` connection needs a Confidential analysis key bound to this exact campaign
Tool returns `protected_corpus_audit_failed`	The durable access audit could not be written, so no protected content was returned; retry or contact an administrator
Tool returns `rate_limited`	Per-connection tool-call budget exhausted — retry in a minute
Tools list but calls fail	Often a workspace mismatch or insufficient key scope — verify that the key was created in the intended workspace and has the required access level

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

Connect a client

Claude.ai and Claude Desktop

Claude Code

API-key access levels

LangDock

Cursor

Codex

Other clients

Confidential client boundary

Rate limits

Troubleshooting

​Claude.ai and Claude Desktop

​Claude Code

​API-key access levels

​LangDock

​Cursor

​Codex

​Other clients

​Confidential client boundary

​Rate limits

​Troubleshooting

Claude.ai and Claude Desktop

Claude Code

API-key access levels

LangDock

Cursor

Codex

Other clients

Confidential client boundary

Rate limits

Troubleshooting