Authentication and scopes

The MCP server authenticates with the same Titan API keys as the rest of the platform. There is no separate agent login and no OAuth flow—one key, sent as a bearer token.

Authorization: Bearer titan_sk_...

Two layers of authorization

Every call passes two checks:

Connection check

The /mcp endpoint verifies the key is valid and carries at least one mcp:* scope. A key with no MCP scope cannot connect at all.

Per-tool check

Each tool then verifies its own scope. A key scoped only to mcp:search connects fine, but calling titan_fetch returns forbidden.

This is deliberate. It lets you issue a narrow key to an agent that should only ever search, without trusting the agent to restrain itself.

Scope per tool

Tool	Required scope
`titan_search`	`mcp:search`
`titan_fetch`	`mcp:fetch`
`titan_crawl`	`mcp:crawl`
`titan_run_template`	`mcp:templates:run`
`titan_get_run`	`mcp:runs:read`
`titan_list_templates`	None beyond connecting

Any agent that starts a run should also carry mcp:runs:read. Without it, a run that exceeds the synchronous wait window returns a run_id the agent cannot poll.

Create a key

Create keys with a JWT from an authenticated session:

curl -sS -X POST "$AUTH_URL/api/v1/api-keys" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research agent",
    "scopes": ["mcp:search", "mcp:fetch", "mcp:runs:read"]
  }'

The key in the response is shown once. Store it in a secret manager, not in a config file you commit.

Recommended scope sets

Grant the smallest set that does the job.

Agent type	Scopes	Rationale
Research assistant	`mcp:search`, `mcp:fetch`, `mcp:runs:read`	Discovers and reads pages; never crawls whole sites
Read-only reader	`mcp:fetch`, `mcp:runs:read`	You supply the URLs; the agent only reads them
Site indexer	`mcp:crawl`, `mcp:fetch`, `mcp:runs:read`	Maps a site, then reads selected pages
Full access	All five	Development and prototyping

Scopes are fixed when a key is created and cannot be widened afterwards. To change what an agent can do, create a new key and revoke the old one.

Key handling

Practice	Why
Send keys in the `Authorization` header only	The server rejects keys in query parameters, which leak into logs and history
Use one key per agent	Revoke a compromised agent without disrupting the others
Keep keys out of version control	Use your client’s secret input mechanism—see Connect your client
Rotate on a schedule	Long-lived keys accumulate exposure

Ownership and isolation

The key identifies a Titan user, and every downstream call inherits that identity:

Runs are created under your account and count against your credits.
titan_get_run can only read runs owned by the same user. An agent cannot poll someone else’s run_id.
Results, datasets, and exports enforce the same ownership as the Task Service API.

Auth errors

Response	Meaning	Fix
`401 missing_authentication`	No bearer token in the request	Confirm your client forwards the `Authorization` header
`401 invalid_api_key`	Key is unknown, revoked, or malformed	Verify the key starts with `titan_sk_` and is still active
`401 query_string_api_key_rejected`	Key was passed in the URL	Move it into the `Authorization` header
`403 insufficient_scopes`	Key carries no `mcp:*` scope	Create a new key with MCP scopes
`forbidden` in a tool result	Key lacks that tool’s specific scope	Create a new key including the missing scope

Full error semantics are in Errors and warnings.

Next steps

Connect your client — where the key goes in each client
Authentication and API keys — the full platform scope catalog
Credits and usage — what each authorized call costs

Get started

Tool reference

How it works

Integration examples

Two layers of authorization

Scope per tool

Create a key

Recommended scope sets

Key handling

Ownership and isolation

Auth errors

Next steps

​Two layers of authorization

​Scope per tool

​Create a key

​Recommended scope sets

​Key handling

​Ownership and isolation

​Auth errors

​Next steps

Two layers of authorization

Scope per tool

Create a key

Recommended scope sets

Key handling

Ownership and isolation

Auth errors

Next steps