Graph Indexer for Codex CLI: config.toml MCP Setup

Graph Indexer for Codex CLI is a local MCP server that gives Codex exact references, call graphs and change impact. Because Codex keeps MCP servers in ~/.codex/config.toml, npx graph-indexer init prints the TOML block to paste there and writes a managed lookup-rules block into AGENTS.md, which Codex reads.

How do I add Graph Indexer to Codex?

Run init for Codex from the repository root, with Node.js 22.5 or later:

npx graph-indexer init --agents codex

Codex is also auto-selected when the repository has an AGENTS.md or a .codex directory. Unlike other agents, Codex gets no project-level config file from init: the command prints the server entry and leaves your global configuration untouched.

What does `npx graph-indexer init` do for Codex?

For Codex CLI, init does two things:

Action	Detail
Prints a TOML entry	A `[mcp_servers.graph-indexer]` table with `command`, `args` and `cwd` set to the repository
Writes `AGENTS.md`	A managed block with the lookup rules and when to use `find_references`, `call_graph`, `change_impact` and `check_changes`

It also adds .graph-indexer/ to .gitignore.

What does the Codex configuration look like?

Add this to ~/.codex/config.toml. The README’s manual form passes the repository with --repo:

[mcp_servers.graph-indexer]
command = "npx"
args = ["-y", "graph-indexer@3", "serve", "--repo", "/path/to/repo"]

The block init prints uses cwd = "/path/to/repo" in place of the --repo argument. Both point the server at the repository you want indexed.

Does Graph Indexer support hooks in Codex?

Graph Indexer’s hook command understands Codex payloads: the source states that Claude Code’s payload format is shared by Codex, and it recognises Codex tool names such as apply_patch and exec_command. However, init --hooks does not write a Codex hook configuration, so for Codex the supported route is the MCP tools plus the AGENTS.md block.

What does Codex gain from Graph Indexer?

Codex gains eight read-only tools. In a Codex session these are the ones to reach for:

find_references for the exact call sites of a function, with kind set to inherit for subclasses and implementations.
call_graph for callers of callers.
change_impact before changing a signature, and check_changes after.
read_code to read several symbols at once instead of opening whole files.

The AGENTS.md block also tells the agent to explore in one pass and to read the function or the 50 to 100 lines it needs rather than whole files. The tools return plain text, capped and ordered best first. See the tools reference and the install guide.

Frequently asked questions

Why does init not edit the Codex config for me?

Codex keeps its MCP servers in your user-level ~/.codex/config.toml, and init only writes project-level files, so it never edits that global file. Instead it prints the TOML for you to review and paste.

Should I use cwd or --repo for the repository path?

Either one works. The block init prints sets cwd to the repository, while the README's manual example passes --repo instead. With neither, the server indexes the git repository containing its working directory.

Where does Codex read the lookup instructions?

From AGENTS.md, the file Codex reads for project instructions. init adds a short managed block there, between graph-indexer:start and graph-indexer:end markers, and updates it in place when you run init again.

Does this work with several repositories in Codex?

The printed block is tied to one repository through cwd. For several repositories, define one server entry per repo under different names, or omit the path and launch Codex from inside the repository.