# MCP client onboarding and bridge

## Client lifecycle

Each machine client is an independently scoped Hub record bound to one project and environment. New UI records are `pending` and their binding is disabled until an exact, real Authentik subject is activated. The control API returns a client ID, status, last-seen metadata, an Authentik service-account plan, and a safe configuration projection. It never returns a bearer token, app password, refresh token, or shared credential.

Disable and revoke are separate audited actions. Both deny new requests immediately in the registry and remain bounded by a revocation cache ceiling of 60 seconds. A client cannot choose a different project or environment through an MCP request body.

## Generated profiles

- Native MCP 2026 uses Streamable HTTP and protocol revision `2026-07-28`.
- Compatibility clients use the same scoped endpoint with revision `2025-11-25`.
- The Codex stdio profile reads an Authentik app password from a user-only file, obtains a short-lived M2M token and refreshes it before expiry. Static bearer-token environment variables remain supported for compatibility.
- Inspector uses an explicit LAN/internal endpoint and is enabled only through the Compose `inspector` profile.

Configuration contains endpoint, protocol, transport, scopes, client ID, Authentik username and credential reference only. `scripts/authentik_provision_mcp_service_account.py`, `scripts/provision_machine_client.py`, and `scripts/install_codex_mcp.ps1` form the reproducible operator path.

## Bridge safety

The bridge accepts only MCP initialization/notification/ping, bounded tool, resource and prompt methods; rejects oversized or invalid messages; never shells out; never logs credentials; handles JSON and SSE responses; and never includes authorization material in responses. Direct remote OAuth remains the preferred future path once the deployed Authentik supports policy-bound Dynamic Client Registration.

Reconciliation preserves only explicitly managed active clients. Pending clients remain disabled, operator-disabled clients stay disabled, and revoked clients cannot be silently reprovisioned.