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