Skip to main content
Contexity integrates with Codex through an MCP server. Once configured, Codex calls Contexity tools automatically at each stage of a task — you don’t need to type Contexity commands during normal work. The integration keeps context bounded, relevant, and traceable without adding friction to your workflow.

​
Install the Host Config

Run the following steps to register Contexity as an MCP server inside Codex.
1

Preview the config (dry run)

Run the installer with --dry-run to see exactly what changes will be written before committing anything:
contexity --project /path/to/project host install codex --dry-run
2

Apply the config

When the preview looks correct, apply the configuration:
contexity --project /path/to/project --yes host install codex
3

Verify the setup

Run the doctor command to confirm that Codex and the MCP server are correctly connected:
contexity --project /path/to/project doctor
If Codex is not calling Contexity tools, check the host status with contexity --project /path/to/project host status and reinstall the config.

​
Expected Codex Behavior

After setup, Codex should automatically call the following MCP tools at each stage of a task:
ToolWhen Codex calls it
context_start_runAt the beginning of every task
context_retrieve_packBefore making any edits
context_search_projectBefore broad repo exploration
context_impactBefore edits to known files
context_detect_changesAfter every meaningful edit
context_close_runAt task closeout
When metrics display is enabled, Codex also shows the heuristic value summary after relevant tool calls. You can control this behavior — see Manage Metrics Display.

​
Capturing External Sources

When you share a Slack update, issue comment, repository link, docs link, or inspiration link with Codex, Codex should call context_capture_external_reference — not paste the raw external content into model instructions. The call should include:
  • Source locator — the URL or identifier pointing to the original source
  • Source type — for example, slack_thread, github_issue, or docs_link
  • Short reason or summary — why this source matters for the current task
  • Extracted signals — structured takeaways with stable signal keys
  • Trust state hints — when you can indicate the reliability of the source
This ensures external information is stored as traceable, structured references rather than unverified text injected directly into the agent’s context.