Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

2026-10-01 01:36:21 +02:00
commit cb5be898ea
@@ -0,0 +1,65 @@
+# Codex integration
+
+## Production profile
+
+Codex uses one MCP server per project/environment. Production endpoints are:
+
+```text
+https://mcp.example.com/mcp/ludarium/prod
+https://mcp.example.com/mcp/vacatureradar/prod
+https://mcp.example.com/mcp/mobilityops/prod
+```
+
+The deployed Authentik `2025.12.6` supports M2M client credentials and app
+passwords, but not the policy-bound Dynamic Client Registration introduced in
+Authentik `2026.8`. Codex therefore uses the repository's stdio bridge. The
+bridge retrieves five-minute Authentik access tokens and refreshes them without
+putting tokens or app passwords in Codex configuration.
+
+Each profile requires:
+
+- a dedicated Authentik service account and app password;
+- the exact Authentik user UUID as the Hub client subject;
+- one active Hub binding to one project/environment;
+- a local credential file readable only by the current OS user;
+- a Codex stdio entry created by `scripts/install_codex_mcp.ps1`.
+
+## Operator sequence
+
+1. Generate the local credential with `scripts/new_codex_credential.ps1`.
+2. Pipe `scripts/authentik_provision_mcp_service_account.py` into the Authentik
+   container's `ak shell`, passing the credential through a temporary file.
+3. Run `scripts/provision_machine_client.py` in the control API container with
+   the exact returned subject UUID. Supply `--client-id` when activating a
+   pending UI-created record.
+4. Install the profile:
+
+```powershell
+.\scripts\install_codex_mcp.ps1 `
+  -Project '<project>' `
+  -Environment 'prod' `
+  -HubClientId '<hub-client-uuid>' `
+  -OAuthUsername 'svc-mcp-codex-<project>' `
+  -SecretFile '<user-only-credential-file>'
+```
+
+5. Restart Codex and verify the server with `codex mcp list`.
+6. Prove `initialize`, `tools/list`, one read-only invocation, audit creation,
+   and a cross-project denial.
+
+Never copy an app password into `config.toml`, a command argument, Git,
+evidence, UI output, logs or chat. Disabling/revoking the Hub client denies new
+calls even if an Authentik token has not yet expired.
+
+## Useful workflows
+
+Runtime connectors publish these user-invoked prompts:
+
+- `project-context-pack` and `pre-change-impact-review`;
+- `repository-change-review` and `release-readiness`;
+- `production-incident-triage` and `deployment-health-review`;
+- `fleet-operations-morning-brief`.
+
+The Gitea surface also exposes pull-request summaries, bounded changed-file
+metadata, and commit/CI statuses. The Unraid surface exposes an aggregate
+project summary in addition to container health, inspect and bounded logs.