CAAB hosted MCP

Audience: MCP users, partner admins, and CAAB operators

Runtime: OAuth-protected hosted MCP endpoint

Last verified against CAAB contract: August 4, 2026

CAAB exposes tenant management and governed runtime operations through the same OAuth-protected MCP endpoint. Tool discovery is recalculated from the authenticated principal on every request, so role, membership, policy, suspension, and boundary state directly control which tools appear.

Management rollout flags

Management tools require EnableMcpManagement=true. Public Cognito signup with verified email and software-token MFA is controlled separately by EnablePublicMcpSignup=true.

Principal-derived tool discovery

Principal state	Tools returned
Unassigned verified user	Access-status and tenant-onboarding tools only.
partner_admin	Tenant management tools, personal OAuth tools, and administrative status tools.
runtime_member	Personal OAuth tools plus only the imported API operations in the user's active signed boundary.
Suspended user	No imported API tools. Management access is denied according to membership state.
User without a boundary	No imported API tools until a partner admin assigns an active boundary.

Hiding a tool improves the agent experience, but runtime authorization still verifies policy at call time. Tool discovery is not the only security boundary.

Tenant onboarding

Sign up through the configured Cognito hosted UI, verify email, and enroll software-token MFA.
Connect the MCP client to the McpBaseUrl output plus /mcp and complete OAuth authorization.
Call caab_get_my_access to inspect current membership and onboarding state.
When status is onboarding_required, call caab_complete_tenant_setup with a tenant name and idempotency key.

CAAB does not generate an organization ID. The authenticated principal must already carry Crittora-managed custom:orgId. If it is missing, tenant setup returns org_provisioning_required.

Key management tools

Tool	Purpose
caab_get_my_access	Return the caller's tenant membership, role, setup state, and available next actions.
caab_complete_tenant_setup	Complete first tenant setup for a verified principal with an existing Crittora organization claim.
caab_create_user	Send the standard CAAB/Cognito invitation without returning passwords or Crittora credentials.
caab_preview_api_import	Validate an OpenAPI 3.x document or HTTPS URL before committing a tenant-scoped API.
caab_commit_api_import	Create the tenant API after review.
caab_begin_auth_profile_setup	Return a one-use browser setup URL for API keys, bearer tokens, headers, or client secrets.
caab_create_boundary	Assign selected permission IDs and a named auth profile to one user.
caab_start_my_oauth_connection	Start a per-user OAuth connection for upstream providers that require user grants.

Version and idempotency expectations

Mutation rules

Every mutation requires an idempotency key.
Updates, activation, suspension, and revocation require the current expected version.
A stale version returns version_conflict and leaves the resource unchanged.
Auth-profile reads expose redacted metadata only; secret values remain in Secrets Manager.

Two-step deletion

Call caab_prepare_delete to receive dependency impact and a ten-minute, principal-bound confirmation token.
Resolve dependencies, then call caab_confirm_delete.

User deletion is blocked by active boundaries. API and auth-profile deletion is blocked by policy references. Boundary deletion revokes and re-sign-encrypts policy before deleting subject artifacts.

Security and operations

Operational expectations

Management authorization is based on canonical tenant membership and role, not runtime permission boundaries.
API import rejects private, loopback, link-local, non-HTTPS, oversized, and redirect-to-unvalidated targets.
Secret handoff and deletion tokens are stored only as SHA-256 hashes and use DynamoDB TTL.
Mutation audit records contain request hashes and result field names, not values or credentials.
Enable internal tenants first, backfill canonical memberships, then enable existing partners and public signup.

Next: review CAAB runtime authorization and policy enforcement

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