Gateway API, headers, and access keys

Endpoint

All MCP traffic uses a single JSON-RPC endpoint over Streamable HTTP. It implements initialize, tools/list, and tools/call.

POST https://<org>.ucl.dev/mcp

Headers

• Authorization: Bearer <access-key> - authenticates the caller (required).
• X-Org-Id: <org> - the workspace/tenant the call is for (multi-tenant agents).
• X-User-Id: <id> - the end user to act as on per-user connectors.

Access keys

Create one access key per agent or client. Each key carries a scope (which servers it can reach), a role, and an optional ABAC policy. Tokens are shown once and stored only as a hash.

Access key fields

• scope: "all" or an array of connector ids the key can reach.
• role: admin / operator / viewer (display + default policy).
• policy: inline ABAC policy, or policyIds referencing saved templates.
• delegated: true to serve many tenants/users via X-Org-Id / X-User-Id headers.
• identityModeOverride: force org or user on "either" connectors.
• orgId / subject: the fixed tenant + downstream identity for non-delegated keys.

Authentication methods

• Access key: Authorization: Bearer ucl_<token> (shown once, stored only as a hash).
• Gateway OAuth token: issued to an interactive MCP client after the user signs in and consents.
• IdP-signed JWT: verified via JWKS (RS256) or a shared secret (HS256), mapping claims to a principal.
• Mutual TLS: a verified Cloudflare client certificate matched to a configured principal.
• Machine client: OAuth2 client-credentials for headless agents.

Per-call identity override

On "either" connectors, a call may include a reserved "_identity" argument of "org" or "user" to pick the credential for that call. It is stripped before the request reaches the downstream server.