Codex Integration

Applies to: Dispatch v1.0.0, last verified 2026-04-05

This page explains how to connect Codex to Dispatch, either through auto-injection or manual configuration, and how agent spawning works.

Auto-injection

Dispatch auto-injects its MCP configuration into .codex/config.toml when it detects a .codex/ directory in a registered project root. If .codex/ does not exist, injection is skipped. Dispatch never creates the directory itself.

The injected section:

[mcp_servers.dispatch]
url = "http://localhost:<port>/mcp"

Injection is idempotent: if config.toml already contains a [mcp_servers.dispatch] section, Dispatch does not modify it. Content before the injected section is preserved.

Opting out of auto-injection

Remove the [mcp_servers.dispatch] section from .codex/config.toml. Dispatch will not re-add it during the current session. To prevent re-injection permanently, disable Auto-inject MCP config in Settings > Providers.

Manual installation

If you prefer to manage the config file yourself, add this section to .codex/config.toml (create the file if it does not exist):

[mcp_servers.dispatch]
url = "http://localhost:<port>/mcp"

Replace <port> with the port Dispatch is actually running on (check the URL printed in the terminal when the server starts). For a global default across all projects, add the same block to ~/.codex/config.toml.

Available tools

Codex uses the same MCP tool names as all other providers. See MCP Overview: The six Dispatch tools for the full list.

Agent spawning

Codex supports agent spawning. Dispatch can track Codex agents launched with JSON output mode:

codex exec --json "your task description"

The --json flag causes Codex to emit structured output that Dispatch’s session scanner can parse. Sessions appear in the Sessions list and activity feed within the next polling cycle.

For real-time updates, configure HTTP hooks in your Codex agent definitions using the hook URLs shown in Settings > Providers > Codex (same format as Claude Code hooks).