Connect Vindex to Claude Code
Claude Code runs in your terminal and builds from whatever story you hand it. Connecting Vindex gives it a way to check that story before it writes a line, and a rule in CLAUDE.md makes the check automatic.
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
In any terminal, register the server once. The --scope user flag makes it available in every project on this machine; leave it off to add it to the current project only.
Claude Code stores the entry in its own settings. Nothing is written to the repository unless you choose project scope, and no key or token is pasted anywhere.
claude mcp add --transport http --scope user vindex https://mcp.vindexgateway.com/mcpSign in with your Vindex account
Start Claude Code and run /mcp. Select vindex and choose Authenticate. Your browser opens the Vindex sign-in; use the same account you use for the Vindex Portal. New users create their account on this screen and start on the free plan.
When the browser says you are signed in, return to the terminal. The /mcp view shows vindex as connected with three tools and one prompt. Claude Code keeps the session, so you sign in once per machine, not per project.
Score your first story
Paste a story and ask for a score, or run the score-story prompt, which Claude Code exposes as a slash command. Pass the tracker key when you have one so re-checks after edits are free.
The result arrives finding first, then the overall percentage and its band, then the six dimensions if you ask. Claude Code will offer to keep working on the story; that is your call, not Vindex's.
/mcp__vindex__score-storyTry this in Claude
“Score this story with Vindex, story id SHOP-214: As a returning customer I want to reuse a saved address at checkout so I do not retype it. Acceptance criteria: saved addresses appear as options; selecting one fills the form; the default address is preselected.”
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. Claude Code 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
Claude Code reads CLAUDE.md at the start of every session. A three-line rule there turns the check into a habit the agent keeps without being asked.
## 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
/mcp shows vindex but the tools are missing
The sign-in did not complete. Select vindex in /mcp and choose Authenticate again; the browser step has to finish before tools appear.
The browser opened to a sign-in for a different organization
Vindex uses the organization you pick at sign-in as your company. Sign out in the browser, run Authenticate again, and choose the organization your team scores under.
A score came back as an error sentence
Every Vindex error is one plain sentence the agent can relay: a timeout, a busy company, or an exhausted allowance. Ask Claude Code to run get_usage to see the allowance, or try again 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.
Claude Code was connected to the live Vindex MCP server before this page was published.