Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

docs/04-mcp/CLIENT_ONBOARDING.md

@@ -0,0 +1,22 @@
+# 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.