ITWorx_MCP_Hub-Public/docs/04-mcp/CODEX_INTEGRATION.md

Codex integration

Production profile

Codex uses one MCP server per project/environment. Production endpoints are:

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:

.\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.