How to connect an MCP server to your AI coding agent

Your AI coding agent can already write patches. An MCP server gives it more tools to call while it writes them — file search, browser access, a database client, whatever you wire in. Neither one tells you whether the patch it just wrote actually works, which is the gap this guide closes: connect the server correctly, then put a verification step after it so "tests pass" means tests pass.

Why this matters

MCP (Model Context Protocol) standardizes how an agent talks to external tools. Before it existed, every integration was custom glue code; in 2026 it's the default way Claude Code, Cursor, and Codex reach outside their own sandbox.

That's useful and it's also where teams get burned. An agent with more tools calls more things, touches more files, and produces more "done, tests pass" claims per session. None of that capability checks itself. The connection step below is mechanical — get the config right and the tools show up. The verification step after it is the part that decides whether you can trust what the agent just told you.

Before you start

• Confirm your agent supports MCP natively. Claude Code, Cursor, and Codex CLI all do as of 2026 — older desktop-only or browser-embedded clients may not.
• Have the server's command ready — an npm package, a Docker image, or a local script — plus any API key or environment variable it needs to start.
• Know exactly where your agent reads its config from. Get this wrong and most agents don't throw an error — the tool list just stays empty with no explanation, which is the single most common failure people hit and blame on the server itself.

Set up the MCP config file

1. Locate or create the config file for your agent (see the table below for the standard location).
2. Add an entry under the mcpServers key with a name for your server, e.g. "my-verifier".
3. Set command to the executable (npx, node, python, or a binary path) and args to whatever arguments start the server.
4. Add an env block if the server needs an API key or a project path.
5. Save the file and validate it — a single trailing comma silently breaks the whole config in most JSON parsers.

Expected result: the file parses without error and lists your server by name under mcpServers.

Connect Claude Code to the server

1. Open .mcp.json in your project root, or claude_desktop_config.json for the desktop app.
2. Under mcpServers, add your server's name, command, args, and env.
3. Quit and reopen Claude Code entirely — a window reload is not enough for it to re-read the MCP config.
4. Ask the agent to list its available tools.

Expected result: your server's tools appear by name when the agent lists what it can call.

Connect Cursor to the server

1. Open Cursor Settings, go to the MCP section, or edit .cursor/mcp.json directly if you want it scoped to one project.
2. Add the same mcpServers block — name, command, args, env.
3. Click Reload in the MCP settings panel, or restart Cursor if the toggle doesn't register the change.
4. Check the MCP panel for a green status indicator next to your server's name.

Expected result: the server shows as connected with a nonzero tool count next to it.

Connect Codex to the server

1. Open config.toml (created on first run if it doesn't exist).
2. Add a [mcp_servers.your-server-name] table with command and args keys.
3. Restart the Codex CLI session — it reads MCP config once at startup.
4. Run a prompt that would need the tool and confirm Codex references it.

Expected result: Codex mentions or uses the tool without you having to name it explicitly in the prompt.

Run verification automatically after every agent session

Connecting the server gets tools into the agent's hands. A second, adjacent workflow covers what happens after the agent says it's done: instead of manually re-running the test suite every time an agent claims a fix, wire a sandbox check to fire the moment the session ends.

The Cursor-to-sandbox verification pipeline covers this exact hand-off — the agent finishes, the patch runs in an isolated sandbox, and you get a receipt back instead of taking the agent's word for it. This is a separate step from MCP entirely; MCP moves data in and out of the agent, it doesn't audit outcomes.

Troubleshooting

• Tool list stays empty after adding the server. Almost always a JSON syntax error — a trailing comma or an unescaped quote. Validate the file, then do a full restart, not a reload.
• "Server failed to start" or a spawn error. The command isn't on the agent's PATH. Use an absolute path to the binary, or wrap it with npx so the agent doesn't need it pre-installed globally.
• Tool calls hang or time out. The server process is crashing after launch or waiting on stdin it never receives. Run the exact command manually in a terminal first — if it hangs there too, the server's the problem, not the agent.
• The agent calls the tool but keeps claiming success anyway. MCP returns text to the agent; it doesn't force the agent to treat that text as a verdict. This is a verification gap, not an MCP config problem — see the section above.
• Duplicate server entries after a restart. Usually a project-level config and a global config both defining the same server name. Pick one location as the source of truth and remove the other.

Customize your workflow

Once the MCP connection is stable, the higher-leverage move is deciding what happens to every patch the agent produces before it reaches a pull request. Teams running Claude Code or Codex against real codebases in 2026 increasingly treat the agent's "tests pass" message as a starting claim, not a conclusion — the same pattern that made verifying AI-generated code before merging worth a dedicated step in the pipeline rather than a manual spot-check.

If you're on AdaptOrch, the sandbox run and the readable receipt sit downstream of whatever MCP servers you've connected — it doesn't care how the patch was produced, only whether it actually works when re-run in isolation.

FAQ

One last thing

Most "MCP isn't working" reports trace back to a restart, not a config error — the agent cached the old tool list and needs a full relaunch, and skipping that step wastes more debugging time in 2026 than the actual JSON syntax ever does. Fix the restart habit first, then chase config bugs.

Related guides

• Flag environment failures automatically when Claude Code tests fail
• Codex to verified patches before deploy: complete workflow