Where is Cursor's MCP config file?

~/.cursor/mcp.json for global servers, or .cursor/mcp.json inside a project for project-specific servers.

Why does Cursor say my MCP server failed to start?

Often the command isn't on the PATH Cursor sees. Use an absolute path for the command, and check the server's own error output.

Can I test my MCP server without Cursor?

Yes. Record one session, export it, and run relayorb check against the server in CI. It replays the recorded calls and reports any answer that changed.

Cursor MCP: configure servers in mcp.json and see what they do

Updated 2026-10-05

Cursor's agent can call tools from any MCP server you configure. This guide covers the mcp.json format, where to put it, and how to record the agent's tool calls when something goes wrong.

Where Cursor reads MCP servers from

Cursor reads MCP servers from ~/.cursor/mcp.json for all projects, and from .cursor/mcp.json in a project folder for that project only. Each entry gives the command that starts the server and its arguments.

.cursor/mcp.json

{
  "mcpServers": {
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}

Record every tool call

To see exactly what Cursor's agent sends and receives, make relayorb the command and move the real server after --. Use the absolute path to relayorb, because desktop apps don't always inherit your shell's PATH. Run which relayorb to find it.

.cursor/mcp.json with RelayOrb

{
  "mcpServers": {
    "fs": {
      "command": "/Users/you/.local/bin/relayorb",
      "args": ["record", "--name", "cursor-fs", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}

Inspect what happened

Use the agent as usual, then open a terminal. relayorb list shows each recorded session, and relayorb show cursor-fs prints the timeline of calls with latency and errors. MCP tool failures (results with isError: true) are flagged as tool errors.

Terminal

relayorb list
relayorb show cursor-fs

Install RelayOrb

Free and open source (Apache-2.0). A single binary for macOS, Linux, and Windows. No account, no cloud, no telemetry.

macOS / Linux

curl -fsSL https://relayorb.com/install.sh | sh

Windows and other options: GitHub Releases.

FAQ

Where is Cursor's MCP config file?: ~/.cursor/mcp.json for global servers, or .cursor/mcp.json inside a project for project-specific servers.
Why does Cursor say my MCP server failed to start?: Often the command isn't on the PATH Cursor sees. Use an absolute path for the command, and check the server's own error output.
Can I test my MCP server without Cursor?: Yes. Record one session, export it, and run relayorb check against the server in CI. It replays the recorded calls and reports any answer that changed.