CAAB MCP guide

Audience: MCP users, CAAB administrators, and integration engineers

Transport: OAuth-protected Streamable HTTP

Last updated: August 9, 2026

CAAB makes least-privilege authority available through MCP. It can expose CAAB-managed API operations as tools, administer a tenant through role-aware management tools, and broker selected tools from a registered remote MCP server. In every case, tool visibility is a convenience; the verified policy is checked again at call time.

One connection, scoped results

Users connect to the shared CAAB MCP URL. CAAB derives the caller's role and effective policy from the OAuth session rather than trusting a client-selected tenant, role, or tool list.

MCP surfaces

Surface	What it does	Authority boundary
CAAB-hosted MCP	Presents CAAB management tools and policy-approved API or MCP operations on one endpoint.	OAuth identity, tenant membership, role, and verified permission boundary.
Registered remote MCP	Imports a partner-scoped catalog from a downstream Streamable HTTP MCP server and exposes selected tools through CAAB.	Signed operation snapshot plus the immutable, current downstream catalog.
Partner-hosted MCP	Lets a partner-hosted application or MCP use CAAB's binding-scoped broker for governed execution.	Binding-scoped workload client, external user assertion, active mapping, and verified v2 policy.

These surfaces are related but distinct. Registering a remote MCP lets CAAB broker a downstream server; configuring a partner-hosted MCP lets a partner own its client experience while calling the CAAB broker.

Connect to CAAB-hosted MCP

1MCP URL: https://<caab-host>/mcp
2OAuth resource: https://<caab-host>/mcp
3Required scope: https://<caab-host>/mcp/tools
4
5CAAB publishes protected-resource and authorization-server metadata under
6/.well-known so compatible Streamable HTTP MCP clients can discover OAuth.

Use the MCP URL supplied by CAAB and let the client complete its OAuth authorization flow.
CAAB validates the access token and resolves canonical membership before responding to tool discovery or a call.
Reconnect after an administrator changes server branding; some MCP clients cache the displayed name and icon.

Treat a user-specific connection URL and OAuth session as sensitive. Do not place either in source control, prompts, support tickets, or a shared browser profile.

Role-aware management tools

When MCP management is enabled for an environment, the endpoint derives its management-tool set on every request. Administrative authorization comes from tenant membership and role, not from a runtime permission boundary.

Caller state	Available tools
Verified user without a tenant	Access status and tenant onboarding.
Partner administrator	Tenant, user, API catalog, auth-profile, boundary, revision, and controlled-deletion management; plus personal OAuth tools.
Runtime member	Personal OAuth connection tools and only the runtime operations allowed by their active boundary.
Suspended user or user without an active boundary	No imported runtime API tools.

Management mutations require an idempotency key. Updates, activation, suspension, revocation, and other versioned changes also require the current expected version; a stale request fails without modifying the resource. Destructive actions use a short-lived, principal-bound confirmation token and report dependencies before deletion.

Secrets are deliberately excluded from MCP arguments. An administrator starts an auth-profile setup handoff in MCP, then enters secret values in the one-use browser page. CAAB returns only redacted metadata.

Register and govern a remote MCP server

In CAAB Admin, add an MCP Server capability with a public HTTPS Streamable HTTP endpoint. Embedded credentials and query strings are rejected.
CAAB initializes the downstream server and discovers its tools, schemas, annotations, protocol version, and transport contract. It saves an immutable catalog version.
Review the discovered tools and create a permission boundary that selects only needed tool permission IDs and an auth profile.
CAAB compiles the selected tool contracts into the signed, encrypted policy. A tool's permission ID includes a normalized name and hash so name normalization cannot create collisions.

A remote MCP server change is not silently inherited. If its endpoint, protocol, transport, catalog version, or selected tool contract differs from the signed policy, CAAB fails closed. Review the new catalog and recompile affected boundaries before users can call changed tools.

Runtime enforcement for MCP calls

Step	CAAB behavior
Discover	Builds dynamic tools only from the caller's verified, active policy and role.
Authorize	Checks the exact permission again when tools/call is received; a cached client tool list grants nothing.
Validate	Validates tool arguments against the signed schema and rejects missing required or disallowed keys.
Verify catalog	For remote MCPs, compares the signed snapshot with the immutable catalog and current capability before forwarding.
Execute	Initializes the downstream session, verifies protocol negotiation, injects the selected auth profile, and invokes tools/call with bounded time and response size.
Protect output	Applies response redaction, records safe audit data and metering, and never returns stored credential material.

CAAB supports no auth, static headers/bearer/API-key profiles, OAuth client credentials, per-user OAuth, and configured token-exchange patterns where applicable. Downstream MCP authentication in a query string is not supported.

Partner-hosted MCP and managed messaging

A partner-hosted application or MCP calls the broker instead of receiving CAAB's shared user session. It sends its binding-scoped service access token, a partner-issued end-user access token in X-CAAB-User-Assertion, the binding ID, permission ID, validated arguments, and purpose. CAAB derives the subject and the immutable operation snapshot; callers cannot select either.

Activation requires the matching OIDC/JWKS and protected-webhook test to succeed for the same configuration version. Webhook delivery is at-least-once, so receivers must deduplicate by event ID and accept a successful HTTP 2xx response. Restoring legacy behavior returns the profile to CAAB-hosted MCP and Cognito identity while retaining the external mappings and delivery history.

Next: integrate the binding-scoped Partner API

Operations and troubleshooting

Symptom	Check
No tools appear	Confirm OAuth authentication, active membership, role, boundary status, policy expiry, and the intended permission IDs.
A remote tool is denied after a server update	Treat it as catalog drift. Review the new server catalog and update/recompile the boundary; do not bypass the verification failure.
OAuth-backed downstream call fails	Confirm the auth-profile type, ownership, token settings, and—when per-user OAuth is used—that the caller completed their personal connection.
MCP client shows old name or icon	Reconnect the client after branding changes so cached server metadata is refreshed.
A management mutation conflicts	Fetch the current resource version, reconcile the change, then retry with a new idempotency key and current expected version.

Review MCP audit records for permission ID, status, duration, redaction events, and safe request/response representations. Use usage and diagnostics views to distinguish authorization failures, OAuth setup failures, upstream errors, and incomplete deployment.

Crittora CAAB

Govern which operations an AI agent, user, or API client can invoke, with signed policy integrity and runtime enforcement.

Least privilege

Runtime enforced

Auditable