Connect a client

Ontora exposes a dedicated OAuth surface for Claude and a legacy API-key surface for service integrations:

Client path	US workspace	EU workspace
Claude OAuth connector	`https://api.ontora.com/mcp/directory`	`https://api.eu.ontora.com/mcp/directory`
API-key integration	`https://api.ontora.com/mcp`	`https://api.eu.ontora.com/mcp`

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: OAuth

Use /mcp/directory for Claude. Claude discovers the required user:org:read and ontora:mcp scopes and manages access-token refresh; you never paste an API key into Claude.

Add a custom connector

Open Settings → Connectors in Claude.ai or Claude Desktop and choose Add custom connector. Name it Ontora, then enter your regional Claude OAuth connector URL from the table above.

Connect your Ontora account

Select Connect. Sign in to Ontora, review the consent request, and select the Ontora organization that Claude should use. The selected organization determines the workspace for every tool call.

Verify permissions

Enable the Ontora tools in a new conversation and ask Claude to call get_my_permissions, then “list my Ontora campaigns.” Members receive read access; workspace admins can also use write tools.

The Claude OAuth surface exposes 42 standard tools. It intentionally excludes get_corpus_manifest, get_corpus_manifest_page, and get_corpus_record; OAuth admin access never grants Confidential corpus access. Use the private API-key flow below for an explicitly approved Confidential analysis. Once Ontora is available in Claude’s official Connector Directory, select Ontora there instead of adding the same URL manually. The authorization and workspace-selection flow is identical.

Claude Code: OAuth

claude mcp add --transport http ontora https://api.ontora.com/mcp/directory

Run /mcp in Claude Code, choose Ontora, and complete the browser sign-in, consent, and organization selection. For an EU workspace, substitute https://api.eu.ontora.com/mcp/directory.

API-key clients: legacy `/mcp` surface

The /mcp endpoint remains available for LangDock, Cursor, Windsurf, automation, and other clients that supply a static Bearer token. It exposes all 45 tools, including the three Confidential corpus tools 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, or via the API:

curl -X POST https://api.ontora.com/v1/api-keys \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LangDock",
    "workspace_id": "8f4a2c10-5d3b-4e6f-9a71-2b8c0d5e7f31",
    "scopes": ["read", "write"]
  }'

Use "scopes": ["read"] for a read-only key. Copy the returned 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 Authentication, Header Type Authorization: Bearer, and the raw ont_live_... key as the value. Do not type Bearer into the value field a second time.

Claude Desktop with an API key (legacy)

Prefer the native OAuth connector above. If an approved workflow specifically requires a workspace API key, Claude Desktop’s JSON configuration can launch mcp-remote as a bridge to the legacy Streamable HTTP endpoint; this requires Node.js. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "ontora": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.ontora.com/mcp",
        "--header",
        "Authorization:${ONTORA_AUTH}"
      ],
      "env": {
        "ONTORA_AUTH": "Bearer ont_live_..."
      }
    }
  }
}

Restart Claude Desktop. The environment-variable indirection keeps the key out of the process arguments. The Ontora tools then appear under the tools menu.

Cursor

Add to ~/.cursor/mcp.json:

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

Claude Code with an API key (legacy)

claude mcp add --transport http ontora https://api.ontora.com/mcp \
  --header "Authorization: Bearer ont_live_..."

Prefer the OAuth command above for normal use. Use user scope or another private local scope only when an approved workflow requires a Confidential analysis key. Never commit a campaign-bound key to a project .mcp.json.

Windsurf

Add an MCP server in Settings → Cascade → MCP servers with:

URL: https://api.ontora.com/mcp
Auth header: Authorization: Bearer ont_live_...

Other clients

Any client that speaks the Model Context Protocol over streamable HTTP can connect — point it at https://api.ontora.com/mcp with the Bearer header. The server does not offer the legacy SSE transport; if your client asks, choose streamable HTTP.

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 OAuth connection or 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 cannot start authorization	Confirm that the custom connector uses the regional `/mcp/directory` URL exactly, without a trailing slash; do not use `/mcp` or paste an API key
OAuth returns `401 Unauthorized`	Reconnect the connector, select an Ontora organization during consent, and confirm that your user still belongs to that workspace
Tool returns `admin_required`	The connected Ontora user is a workspace member; an admin must perform that write action or change the user’s role
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
Confidential tool is absent in Claude	Expected: `/mcp/directory` never exposes Confidential corpus tools; use an approved private `/mcp` API-key connection
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 — reconnect OAuth with the intended organization, or verify that the key was created in the right workspace

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

Connect a client

Claude.ai and Claude Desktop: OAuth

Claude Code: OAuth

API-key clients: legacy `/mcp` surface

LangDock

Claude Desktop with an API key (legacy)

Cursor

Claude Code with an API key (legacy)

Windsurf

Other clients

Confidential client boundary

Rate limits

Troubleshooting

​Claude.ai and Claude Desktop: OAuth

​Claude Code: OAuth

​API-key clients: legacy /mcp surface

​LangDock

​Claude Desktop with an API key (legacy)

​Cursor

​Claude Code with an API key (legacy)

​Windsurf

​Other clients

​Confidential client boundary

​Rate limits

​Troubleshooting

Claude.ai and Claude Desktop: OAuth

Claude Code: OAuth

API-key clients: legacy `/mcp` surface

LangDock

Claude Desktop with an API key (legacy)

Cursor

Claude Code with an API key (legacy)

Windsurf

Other clients

Confidential client boundary

Rate limits

Troubleshooting