Codex
Connect Codex, the OpenAI coding agent, to SpecsGraph with an mcp_servers entry in config.toml, and tell it to read the spec first through AGENTS.md.
Before you start
- Codex installed and signed in, as the CLI or the IDE extension.
- A SpecsGraph account in an organisation, with the Editor role or above if the agent should stage changes. A Viewer's agent reads, comments and asks questions.
- The SpecsGraph MCP URL,
https://mcp.specsgraph.io/mcp; see The MCP URL.
Add the server to config.toml
Codex reads MCP servers from ~/.codex/config.toml. A remote server takes a url. Add the entry, then log in: Codex opens your browser, where you pick the organisation, access and projects and choose Allow.
[mcp_servers.specsgraph]
url = "https://mcp.specsgraph.io/mcp"codex mcp login specsgraphcodex mcp add specsgraph --url https://mcp.specsgraph.io/mcp writes the same entry from a shell.
With a personal access token
Without sign-in, send a personal access token in a header, read from the environment so the file holds no secret. Set SPECSGRAPH_TOKEN in the shell that starts Codex.
[mcp_servers.specsgraph]
url = "https://mcp.specsgraph.io/mcp"
[mcp_servers.specsgraph.http_headers]
Authorization = "Bearer $SPECSGRAPH_TOKEN"
# Older Codex releases read the header through env_http_headers instead:
# [mcp_servers.specsgraph.env_http_headers]
# Authorization = "SPECSGRAPH_TOKEN"Codex expands the variable when it starts. If your release does not expand variables in http_headers, use the env_http_headers form, which names the variable that holds the value.
Note
Codex's own documentation is the authority on config.toml and its MCP settings. The examples here reflect Codex at the time of writing.
Check the connection
Run codex mcp list from a shell: the specsgraph entry lists its 35 tools, starting with project_list, once the sign-in or token is accepted. Inside a session, /mcp shows the same. If the server shows an error, check that SPECSGRAPH_TOKEN is set in the environment that starts Codex when you use a token, then see the troubleshooting table in Other MCP clients, or press Test connection in the web app's token created dialog.
Tell Codex to consult SpecsGraph first
Codex reads AGENTS.md at the repository root at the start of every session. The same section works for Claude Code (through @AGENTS.md in CLAUDE.md) and Cursor.
## Specs live in SpecsGraph
This repository's spec (bounded contexts, aggregates, use cases, features, glossary terms) is in
SpecsGraph, available through the `specsgraph` MCP server. Main is the spec that shipped; a workstream
(WS-3) holds the spec in flight until one of its tasks publishes.
Before you change behaviour, read first:
1. `project_list` to find the project, then `spec_get` for the documents you touch (selector `kind/Name`):
`scope: workstream:WS-n` while the spec is in flight in that workstream, `scope: main` for what shipped.
2. `workstream_list` and `workstream_listChanges` to see what a workstream already changes.
3. `task_list` and `thread_list` for the task and the review threads (open questions) you are working on.
When behaviour changes:
- Stage the spec change with `spec_apply` into the workstream. It lands in a proposal that a person
reviews: accepted into the workstream; Main after a task publishes.
- One small proposal per change. Do not treat an open proposal as final; read the workstream, not Main,
for what was accepted.
- People mark a task Ready and publish it; publishing moves the task on and the landing marks it done.
- Cite display ids such as WS-3 and T-4 (or the task's tracker key, such as KAN-43) in commit
messages and pull request descriptions.Example prompts
Next steps
- Working well with agents: habits that keep proposals small and easy to review.
- MCP tool reference: what each tool reads or stages.
- Sign-in and access tokens: rotate and revoke the access Codex uses.