> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Codex

> MCP server and AGENTS.md guidance for Codex

Codex does not have a cross-platform lifecycle-hook mechanism, so the
integration uses two pieces: the MCP server (scan tools) and `AGENTS.md`
guidance (when to use them). There is no deterministic stop-hook enforcement
for Codex — if you need that guarantee, pair Codex with ZeroPath PR scanning
so the diff is caught at review time.

## What the installer writes

| File                                              | What                                                                                                                                                  |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.codex/config.toml` → `[mcp_servers.zeropath]` | ZeroPath MCP server                                                                                                                                   |
| `~/.codex/AGENTS.md`                              | Managed guidance block (between `<!-- BEGIN/END ZEROPATH AGENT INTEGRATION -->` markers) telling Codex to scan code it writes before finishing a task |

## Manual MCP setup

Append to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.zeropath]
command = "uvx"
args = ["--from", "git+https://github.com/ZeroPathAI/zeropath-mcp-server", "zeropath-mcp-server"]

[mcp_servers.zeropath.env]
ZEROPATH_TOKEN_ID = "your_token_id"
ZEROPATH_TOKEN_SECRET = "your_token_secret"
# ZEROPATH_ORG_ID = "..."        # multi-org accounts
# ZEROPATH_BASE_URL = "..."      # self-hosted
```

## Notes

* If your Codex deployment restricts MCP servers (managed/cloud config or an
  `mcp_servers` allowlist), `zeropath` must be included in that allowlist;
  cloud-managed configuration takes precedence over `~/.codex/config.toml`.
* The `zeropath` CLI is installed at `~/.zeropath/bin/zeropath`, so Codex can
  also scan from the shell:
  `~/.zeropath/bin/zeropath scan-code --diff --base-ref HEAD --caller agent --json`.
  The `AGENTS.md` guidance mentions this as the fallback when MCP is
  unavailable.

## Verify

Run `/mcp` in the Codex TUI and confirm `zeropath` is listed, or:

```bash theme={null}
grep -A3 'mcp_servers.zeropath' ~/.codex/config.toml
```

Then ask Codex to "scan my uncommitted changes with ZeroPath" — it should call
`asyncCodeScans.submit`, poll `asyncCodeScans.status`, and report the
`asyncCodeScans.results` findings.