Connect Vindex to Codex
Codex takes a task and works it through to a change. When the task is a user story, Vindex gives Codex a way to judge the story first, and AGENTS.md is where the rule lives so the agent checks without being told each time.
Three steps, about 3 minutes. Open to every registered Vindex user; new users create an account during sign-in.
The walkthrough
Add the Vindex MCP server
From a terminal, register the server with the Codex CLI. This writes an entry to Codex's configuration, so the same server is available in the CLI and the IDE extension on this machine.
If you prefer editing the file, add a [mcp_servers.vindex] table to ~/.codex/config.toml with the url below. No key is stored in the file; sign-in happens in the next step.
codex mcp add vindex --url https://mcp.vindexgateway.com/mcpSign in with your Vindex account
Run the login command for the server. Codex opens your browser on the Vindex sign-in; use the account you use for the Vindex Portal, or create one to start on the free plan.
When the browser confirms the sign-in, Codex records the session. Running codex mcp list shows vindex as authenticated.
codex mcp login vindexScore your first story
Start Codex in a project and give it a story with the request to score it first. Codex calls score_story, then reports the finding, percentage, and band before it does anything else.
Pass the tracker key in the request. Codex sends it as the story id, so when you edit the story and ask again, the re-check is free.
Try this in Codex
“Before doing any work, score this story with Vindex using story id NW-105, then tell me the finding and whether you would start: As a customer I want an ETA email when my delivery is delayed. Acceptance criteria: the customer receives an email with the new ETA; the email includes the order number and new window; the customer can opt out in settings.”
What comes back
The result reads finding first: the one change that moves the score most, in plain language. Then the overall percentage and its band (Healthy 80 to 100, Needs review 60 to 79, At risk 0 to 59), then the six INVEST dimensions with reasons and suggestions when you ask for them.
The band is Vindex’s suggestion. Codex does not stop or change anything on its own; what happens next is your call. Fix the story and ask again: the re-check of a counted story is free.
Make the check automatic
Codex reads AGENTS.md from the repository root (and parent directories) at the start of a task. A ready-check rule there applies to every story Codex is handed in that repository.
## Before implementing a story
1. Score it with the Vindex score_story tool. Pass the tracker key as story_id.
2. Healthy: proceed. Draft the acceptance checks from the Testable reasoning before writing code.
3. Needs review or At risk: do not write code. Report the finding and the top
recommendations, and ask the product owner the open questions.The threshold is the team’s to set; see putting a ready check into your agent’s standing instructions.
Troubleshooting
codex mcp login vindex does not open a browser
Copy the URL Codex prints into a browser by hand, complete the sign-in, and return to the terminal. On a remote machine, run the login step locally and let Codex sync the configuration.
Codex started building without scoring
Put the rule in AGENTS.md so it applies to every task, and say 'score it with Vindex first' in the request until the file is in place. Agents follow the instructions they can see.
The score tool returned one sentence
That sentence is a Vindex error: a timeout, a busy company, or an exhausted allowance. Ask Codex to call get_usage, or retry in a moment.
Using a different client?
Next steps
Finding first, then the band, then the dimensions.
Score before building; proceed on Healthy.
Endpoint, sign-in, tools, limits.
Codex was connected to the live Vindex MCP server before this page was published.