MCP bridge documentation

Call the first advertised route:

POST {api_base_url}/v1/auth/local/public/registrations

Send the exact allowlisted Origin when you provide one. If you omit it, the server uses the configured default origin. Do not send Authorization.

The request body has these fields:

{
  "email": "<email>",
  "display_name": "<display_name>",
  "password": "<password>",
  "redirect_uri": "<redirect_uri>"
}

Send an empty string for redirect_uri when you do not need a redirect.

The first successful registration returns HTTP 201 and this body shape:

{
  "user_id": "<user_id>",
  "tenant_id": "<tenant_id>",
  "email": "<email>",
  "display_name": "<display_name>",
  "created_at": "<RFC3339 timestamp>",
  "verification_id": "<verification_id>",
  "verification_expires_at": "<RFC3339 timestamp>",
  "workspace_slug": "<workspace_slug>",
  "origin": "<origin>",
  "verification_email_state": "accepted"
}

The verification token is delivered in the verification email sent to the registered address.

A successful public registration always returns verification_email_state as accepted. This is local request acceptance, not provider delivery, and it does not disclose whether an account already exists.

With an Idempotency-Key, registration creates the tenant and its owner membership before verification. Without the key, registration stores a provisional account and defers the tenant and owner membership until verification. The account cannot use local-password login until verification succeeds.

Send a caller-generated Idempotency-Key header on every registration. The key must be a high-entropy random value. Its entropy must make guessing the key infeasible. This handler does not validate key length or entropy. The header is the only key carrier for this route; do not add an idempotency field to the JSON body. Use a new key for a new registration body.

If the response is lost because of a timeout, a gateway 504, or an untyped body, retry the identical body with the same Idempotency-Key. The server returns the original HTTP status and response body. The gateway timeout case is tracked in #12455.

The same key with a different registration body returns HTTP 409 with denied_reason: "idempotency_conflict" in the local-auth error envelope. Do not use a new key for the same body.

Duplicate-class accounts return neutral HTTP 201 data. Treat that response as non-disclosing. Do not use it to decide whether an account exists.

An unknown or expired key is processed as a new request. The caller sees the ordinary response for that request. A duplicate-class request therefore receives the neutral HTTP 201 registration shape. The response does not say whether the key was used before. The server retains a keyed registration outcome for 24 hours from creation. On a keyed lookup, the server reclaims the requested expired row and up to 100 other expired rows. A replay after 24 hours is processed as a new request. If a stored key is absent, use the same unknown-key behavior.

After a successful original outcome, the next step is to request the verification email again when needed:

POST {base_url}/v1/auth/local/public/email-verification-resends

Send the registered email and password. This route keeps its generic response for every account state.

Principal registration denials use the local-auth envelope. The source maps these denials as follows:

Malformed JSON also fails with a local-auth error. Do not retry malformed JSON.

Read the verification token from the verification email sent to the registered address.

Do not call the internal email-verification issue route.

A machine principal does not take this path at all. The steps above register a human account, and a person with access to the registered address must complete email verification once.

The path that is served for a machine principal starts from a tenant that already has a verified owner. That owner mints an enrollment token with an authenticated call to POST /v1/machine-credentials/enrollment-tokens, which returns enrollment_token and its expires_at, and hands the token to the agent out of band. The agent redeems it at POST /v1/machine-credentials/enrollments, sending tenant_id, enrollment_token, a display_name, the scopes it needs, and an expires_at. It receives a machine credential. That redemption needs no inbox, no account, and no session.

One human step therefore remains, and it is worth asking for plainly rather than working around: a person verifies their email once and issues the enrollment token. An agent that reaches this point should say "verify your email, then give me an enrollment token" instead of stopping.

Call the second advertised route:

POST {api_base_url}/v1/auth/local/public/email-verification-consumptions

Send the required Origin header with the origin value from the registration response.

Do not send a bearer, session cookie, tenant header, or CSRF header. The body has two fields:

{
  "verification_token": "<verification_token>",
  "password": "<password>"
}

For public provisional registration, including keyed registration, password is a new password chosen by the verifying mailbox owner. It replaces the registration password and need not match it. Invite and MCP verification are token-only only when the address has no pending public registration.

Successful consumption returns HTTP 200:

{
  "user_id": "<user_id>",
  "tenant_id": "<tenant_id>",
  "email": "<email>",
  "email_verified_at": "<RFC3339 timestamp>"
}

The response can also contain invite_acceptance, session, and next_path. The optional invite_acceptance object has invite_id, membership_id, user_id, tenant_id, role, and accepted_at. The optional session object has tenant_id, session_id, actor_id, role, auth_assurance_level, auth_fresh_at, auth_fresh_until, idle_expires_at, expires_at, csrf_token, redirect_uri, evidence_refs, and workspace_name. The public registration path normally does not need the optional invite session.

Principal verification denials use the local-auth envelope:

Stop the flow when the token is expired, consumed, or superseded. Start a new registration when the token is unknown.

Call the third advertised route:

POST {api_base_url}/v1/auth/local/public/sessions

Mint this public session on the origin to which steps 8 and 9 post: {api_base_url} when clutch_api_base_url is advertised, or {base_url} otherwise.

Send the allowlisted Origin. Do not send a bearer or a CSRF header for this new-session request. The handler reads tenant_id from the body and does not read X-Clutch-Tenant-ID on this route. Put the registration tenant ID in the body when it is known. A different value in that header is ignored.

The request body has these fields:

{
  "tenant_id": "<tenant_id>",
  "email": "<email>",
  "password": "<password>",
  "redirect_uri": "<redirect_uri>"
}

Use the registration tenant ID when it is known. Send an empty string for redirect_uri when you do not need a redirect.

tenant_id may be an empty string. The handler then verifies the password first and resolves the tenant from the account's current memberships. It creates a session only when there is exactly one. With an empty tenant_id and a correct password, branch on these outcomes:

On 409 disambiguation_required, retry with one of the returned tenant_id values. A wrong password returns 401 invalid_credentials before any of these checks.

Normal success returns HTTP 201, sets the __Host-clutch_session cookie, and returns:

{
  "tenant_id": "<tenant_id>",
  "session_id": "<session_id>",
  "actor_id": "<actor_id>",
  "role": "<role>",
  "auth_assurance_level": "<level>",
  "auth_fresh_at": "<RFC3339 timestamp>",
  "auth_fresh_until": "<RFC3339 timestamp>",
  "idle_expires_at": "<RFC3339 timestamp>",
  "expires_at": "<RFC3339 timestamp>",
  "csrf_token": "<csrf_token>",
  "evidence_refs": ["<evidence_ref>"],
  "workspace_name": "<workspace_name>"
}

redirect_uri appears only when the request asked for one. A session created with an empty or absent redirect_uri omits the field from this body; it does not return an empty string. Do not read the field's presence as a signal about anything other than what the request sent.

Store the cookie and the csrf_token in memory. Use them for browser-session writes. Do not print either value.

A configured claim flow can instead return HTTP 200 with this body:

{
  "claim_continuation": {
    "path": "<path>",
    "handoff_token": "<handoff_token>",
    "expires_at": "<RFC3339 timestamp>"
  }
}

Follow that continuation before using a session-protected route.

Principal session denials use the local-auth envelope:

Stale-authority and insufficient-authority responses can include the authority recovery fields. Do not replace the session cookie with a gateway credential.

Reconcile the default review-authority profile before credential creation:

POST {api_base_url}/v1/project-controls/review-authority/onboarding/reconcile

Send {} as the body. Use the browser-session contract. Do not send the bootstrap gateway bearer.

Creation returns HTTP 201. Repair and already-ready results return HTTP 200. Created and repaired bodies set reconciled to true. The created or repaired response contains:

{
  "code": "<code>",
  "tenant_id": "<tenant_id>",
  "profile": "<profile>",
  "status": "<status>",
  "previous_status": "<previous_status>",
  "reconciled": true,
  "contract_id": "<contract_id>",
  "contract_version": "<contract_version>",
  "authority_matrix_id": "<authority_matrix_id>",
  "authority_matrix_version": "<authority_matrix_version>",
  "role_memberships_version": "<role_memberships_version>"
}

An already-ready result uses code review_authority_onboarding_already_ready and status review_authority_ready:

{
  "code": "review_authority_onboarding_already_ready",
  "tenant_id": "<tenant_id>",
  "profile": "<profile>",
  "status": "review_authority_ready",
  "previous_status": "review_authority_ready",
  "reconciled": false,
  "contract_id": "<contract_id>",
  "contract_version": "<contract_version>",
  "authority_matrix_id": "<authority_matrix_id>",
  "authority_matrix_version": "<authority_matrix_version>",
  "role_memberships_version": "<role_memberships_version>"
}

reconciled: false with review_authority_onboarding_already_ready means no further call is needed; the tenant is already in the ready state.

Principal reconciliation denials use the review-authority error object. The source defines these primary codes:

Create the first machine credential with the browser session:

POST {api_base_url}/v1/machine-credentials/bootstrap

Send Idempotency-Key. After trimming leading and trailing whitespace, its length must be between 16 and 256 bytes. Use a new stable value for this bootstrap attempt. Do not send a gateway bearer.

The request body has these fields:

{
  "tenant_id": "<tenant_id>",
  "display_name": "<bootstrap principal name>",
  "scopes": [
    {
      "tenant_id": "<tenant_id>",
      "permission": "mcp:bridge.read",
      "object_type": "",
      "object_id": ""
    },
    {
      "tenant_id": "<tenant_id>",
      "permission": "mcp:bridge.call",
      "object_type": "",
      "object_id": ""
    }
  ],
  "expires_at": "<RFC3339 timestamp within 90 days>",
  "actor_ref": "actor:<actor_id>",
  "now": "<RFC3339 timestamp or empty string>"
}

owner_membership_id is optional and omitted by default. The server derives the founding owner's membership from the session actor. If supplied, it must match the caller's own membership.

The server binds owner_membership_id and actor_ref to the current actor authority. The handler clears now, and the service resolves the time from its server clock. Send matching membership and actor hints when you have them. The now value does not set the server time. The bootstrap scope list must be non-empty, tenant-wide, unique by permission, and contain no more than eight entries. The allowed permissions are:

• mcp:bridge.read
• mcp:bridge.call
• worker_facade.claim
• governed_execution.read
• governed_execution.write

Every bootstrap scope must use the tenant ID, an empty object_type, and an empty or zero object_id. Use mcp:bridge.read for a first MCP read. Add mcp:bridge.call when the credential must call MCP tools.

Successful bootstrap returns HTTP 201:

{
  "service_principal": {
    "tenant_id": "<tenant_id>",
    "service_principal_id": "<service_principal_id>",
    "display_name": "<display_name>",
    "owner_membership_id": "<owner_membership_id>",
    "state": "<state>",
    "created_at": "<RFC3339 timestamp>",
    "updated_at": "<RFC3339 timestamp>",
    "latest_audit_evidence_id": "<evidence_id>"
  },
  "api_key": {
    "tenant_id": "<tenant_id>",
    "api_key_id": "<bootstrap_api_key_id>",
    "service_principal_id": "<service_principal_id>",
    "owner_membership_id": "<owner_membership_id>",
    "key_prefix": "<key_prefix>",
    "scopes": [
      {
        "tenant_id": "<tenant_id>",
        "permission": "mcp:bridge.read",
        "object_type": "",
        "object_id": ""
      },
      {
        "tenant_id": "<tenant_id>",
        "permission": "mcp:bridge.call",
        "object_type": "",
        "object_id": ""
      }
    ],
    "expires_at": "<RFC3339 timestamp>",
    "created_at": "<RFC3339 timestamp>",
    "latest_audit_evidence": "<evidence_id>"
  },
  "secret": "<bootstrap_secret>"
}

Take service_principal.owner_membership_id from this 201 response and keep it as <owner_membership_id> for steps 8 and 9. Step 8 accepts it as an optional owner_membership_id hint and, when omitted, the server derives it from the authenticated session and calling credential's membership. Step 9 treats it as optional; when supplied, it must match the authenticated owner. The server rejects a mismatch. The optional workspace lookup is not needed to obtain it.

The API-key object can also contain revoked_at, revoked_reason, and last_used_at. The secret is returned once. Store it as the bootstrap gateway credential. Do not log it.

Principal bootstrap errors use the error envelope. The main codes are invalid_request (400), unauthenticated (401), tenant_scope_mismatch (403), actor_authority_mismatch (403), bootstrap_scope_not_allowed (403), normal_policy_required (403), bootstrap_replayed (409), bootstrap_rate_limited (429), actor_not_authorized (403), audit_evidence_unavailable (503), and internal_error (500). A second bootstrap attempt is not a way to mint a second first credential.

Keep two credential uses separate:

• Use <bootstrap_secret> as the SaaS gateway bearer for steps 8 and 9.
• Exchange the bootstrap API-key ID and secret for an OAuth access token for the MCP resource.

The OAuth issuer is {mcp_base_url}/v1/mcp/oauth unless the environment discovery document advertises another issuer. Post form data to its token endpoint:

POST {issuer}/token
Content-Type: application/x-www-form-urlencoded

Send:

grant_type=client_credentials
client_id=<bootstrap_api_key_id>
client_secret=<bootstrap_secret>
resource={mcp_base_url}/v1/mcp
scope=mcp:bridge.read mcp:bridge.call

The response returns access_token, token_type, expires_in, and the granted scope. The client-credentials path does not return refresh_token. The access_token is the MCP bearer. Do not send it as the SaaS gateway bearer.

If bootstrap changes the current browser authority, create a new public session with step 4. Replace both the __Host-clutch_session cookie and the csrf_token before the next browser-session write. A stale browser session must not be used for steps 8 or 9.

Use the bootstrap secret as the gateway bearer and keep the current browser session, allowlisted Origin, matching x-clutch-csrf-token, and optional matching X-Clutch-Tenant-ID:

POST {api_base_url}/v1/service-principals
Authorization: Bearer <bootstrap_secret>

The request body has these fields. owner_membership_id is an optional hint; when supplied, use the UUID from service_principal.owner_membership_id in the step-6 201 response to state the intended membership explicitly. When omitted, the server derives it from the authenticated session and calling credential's membership. Do not invent a membership ID.

{
  "tenant_id": "<tenant_id>",
  "display_name": "<final principal name>",
  "owner_membership_id": "<owner_membership_id>",
  "actor_ref": "actor:<actor_id>",
  "now": "<RFC3339 timestamp or empty string>"
}

A successful response returns HTTP 201:

{
  "service_principal": {
    "tenant_id": "<tenant_id>",
    "service_principal_id": "<final_service_principal_id>",
    "display_name": "<display_name>",
    "owner_membership_id": "<owner_membership_id>",
    "state": "<state>",
    "created_at": "<RFC3339 timestamp>",
    "updated_at": "<RFC3339 timestamp>",
    "latest_audit_evidence_id": "<evidence_id>"
  }
}

Take service_principal.service_principal_id from this response and keep it as <final_service_principal_id> for the step-9 request body.

Principal errors use the error envelope. The main codes are unauthenticated (401), tenant_scope_mismatch (403), actor_authority_mismatch (403), invalid_request (400), not_found (404), actor_not_authorized (403), audit_evidence_unavailable (503), and internal_error (500).

Use the same bootstrap gateway bearer and browser-session headers:

POST {api_base_url}/v1/api-keys
Authorization: Bearer <bootstrap_secret>

The request body has these fields. owner_membership_id is optional; when supplied it must match the authenticated owner. Use the UUID from service_principal.owner_membership_id in the step-6 201 response. The server rejects a mismatch; do not invent a membership ID.

{
  "tenant_id": "<tenant_id>",
  "service_principal_id": "<final_service_principal_id>",
  "owner_membership_id": "<owner_membership_id>",
  "scopes": [
    {
      "tenant_id": "<tenant_id>",
      "permission": "mcp:bridge.read",
      "object_type": "",
      "object_id": ""
    },
    {
      "tenant_id": "<tenant_id>",
      "permission": "mcp:bridge.call",
      "object_type": "",
      "object_id": ""
    }
  ],
  "expires_at": "<RFC3339 timestamp within 365 days>",
  "actor_ref": "actor:<actor_id>",
  "now": "<RFC3339 timestamp or empty string>"
}

The API-key scope contract is:

• Provide at least one scope and no more than eight scopes.
• Set every scope tenant_id to the request tenant ID.
• Set every permission to a non-empty value of at most 64 bytes.
• Set object_type to at most 64 bytes.
• Use an empty object_type and an empty or zero object_id for a tenant-wide MCP scope.
• Set expires_at after the current time and no more than 365 days ahead.
• Do not use saas.api_key.create or saas.machine_credential.manage as an API-key policy scope on this route.

Use mcp:bridge.read for the first entitled MCP read. Add mcp:bridge.call for MCP tool calls. The OAuth scope requested later must be within the scopes on this API key.

Successful creation returns HTTP 201:

{
  "api_key": {
    "tenant_id": "<tenant_id>",
    "api_key_id": "<final_api_key_id>",
    "service_principal_id": "<final_service_principal_id>",
    "owner_membership_id": "<owner_membership_id>",
    "key_prefix": "<key_prefix>",
    "scopes": [
      {
        "tenant_id": "<tenant_id>",
        "permission": "mcp:bridge.read",
        "object_type": "",
        "object_id": ""
      },
      {
        "tenant_id": "<tenant_id>",
        "permission": "mcp:bridge.call",
        "object_type": "",
        "object_id": ""
      }
    ],
    "expires_at": "<RFC3339 timestamp>",
    "created_at": "<RFC3339 timestamp>",
    "latest_audit_evidence": "<evidence_id>"
  },
  "secret": "<final_secret>"
}

The API-key object can also contain revoked_at, revoked_reason, and last_used_at. The secret is returned once. Use it only with the OAuth client-credentials exchange for this final API key. Keep the bootstrap secret and final secret separate.

Principal errors use the error envelope. The main codes are unauthenticated (401), tenant_scope_mismatch (403), actor_authority_mismatch (403), policy_scope_not_allowed (403), invalid_request (400), not_found (404), actor_not_authorized (403), audit_evidence_unavailable (503), and internal_error (500).

Exchange the final API key for the final MCP bearer. Use the final API-key ID and final secret at the same {issuer}/token endpoint:

grant_type=client_credentials
client_id=<final_api_key_id>
client_secret=<final_secret>
resource={mcp_base_url}/v1/mcp
scope=mcp:bridge.read mcp:bridge.call

Use the returned access_token in the MCP Authorization header. Do not use the API-key secret at /v1/mcp.

Initialize the MCP connection with a supported protocol version. Then send the first read as a JSON-RPC tools/list request:

POST {mcp_base_url}/v1/mcp?profile=compact
Authorization: Bearer <final_mcp_access_token>
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Use the normal MCP initialize request and notifications/initialized notification before tools/list when the client requires the handshake. Request mcp:bridge.call in addition to mcp:bridge.read before calling a tool.

The MCP operation is POST-only. GET /v1/mcp sets Allow: POST. With OAuth enabled, it returns HTTP 401 with an authentication challenge when no tenant route is resolved. It returns HTTP 405 when OAuth is disabled or a tenant route is found.