66 lines
2.5 KiB
Markdown
66 lines
2.5 KiB
Markdown
# 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.
|