Debugging MCP servers in Cursor

Finding the MCP Output panel

Cursor logs all MCP protocol traffic to an Output channel. To access it:

1. Open the Output panel: View → Output (or Ctrl+Shift+U / Cmd+Shift+U)
2. Click the dropdown in the Output panel header (it shows the current channel name)
3. Look for channels named MCP or MCP: <server-name>

The MCP channel shows every JSON-RPC message Cursor sent to and received from each server: the initialize handshake, tools/list response (the tool manifest), and each tools/call request/response pair. This is the primary debugging surface for MCP server issues in Cursor.

If you don't see an MCP channel in the dropdown, the server hasn't connected yet. Check that the server is configured correctly in mcp.json and restart Cursor. The MCP channel only appears after Cursor attempts to connect to at least one MCP server.

Configuring a local development server

Cursor reads MCP server configuration from two files:

• .cursor/mcp.json — project-level (applies only in the current workspace)
• ~/.cursor/mcp.json — global (applies in all workspaces)

For development, use the project-level file so your dev server config doesn't affect other projects:

// .cursor/mcp.json — local development server
{
  "mcpServers": {
    "my-server-dev": {
      "command": "node",
      "args": ["--inspect=9229", "/absolute/path/to/my-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgres://localhost/mydb",
        "NODE_ENV": "development",
        "LOG_LEVEL": "debug",
        "DEBUG": "mcp:*"
      }
    }
  }
}

Key rules for Cursor's mcp.json:

• Use absolute paths in args — Cursor doesn't inherit your shell's working directory
• Add all required environment variables in env — Cursor spawns the server in a clean environment
• Restart Cursor (or reload the window with Cmd+Shift+P → "Reload Window") after changing mcp.json
• Adding --inspect=9229 to the node args enables the VS Code debugger to attach to the running server

Two failure modes: initialization vs. handler

When an MCP server doesn't work in Cursor, the failure always falls into one of two categories. Identifying which one immediately tells you where to look:

Reading the MCP Output panel log

The MCP Output panel shows JSON-RPC messages in chronological order. Here's how to read them to diagnose a failing tool:

// A successful tool call sequence in the MCP Output panel:

// 1. initialize handshake (on connection)
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05",...}}
← {"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"my-server","version":"1.0.0"},...}}
→ {"jsonrpc":"2.0","method":"notifications/initialized"}

// 2. tools/list (Cursor fetches tool manifest)
→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"search_docs","description":"...","inputSchema":{...}}]}}

// 3. tools/call (model asks Cursor to call a tool)
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"MCP"}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"[{\"id\":1,\"title\":\"...\""}]}}

// A failing tool call:
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":""}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Error: query must not be empty"}],"isError":true}}

Key things to look for:

• If the tools/list response has an empty tools array → tool registration failed (not the handler)
• If a tools/call response has "isError":true → handler returned an error; read content[0].text for the message
• If a tools/call response is a JSON-RPC error ("error" key, not "result") → handler threw an uncaught exception
• If there's no tools/list message at all → server crashed during initialization; check stderr

Replaying a failing scenario

When you find a failing tools/call in the MCP Output log, the log shows the exact JSON arguments Cursor sent. Use these to reproduce the failure outside of Cursor:

1. Copy the "arguments" object from the failing tools/call request in the MCP Output panel
2. Open the MCP Inspector: npx @modelcontextprotocol/inspector node dist/index.js
3. Navigate to the failing tool in the Inspector's tool list
4. Switch to raw JSON input mode and paste the exact arguments
5. Run the tool call — you'll see the same failure outside of Cursor

This isolates the problem from Cursor's AI behavior — you're now debugging the server directly with the exact inputs that caused the failure. Once you fix the handler, verify in the Inspector, then reload the Cursor window to reconnect the server and confirm the fix works end-to-end.

Common Cursor MCP debugging scenarios

Server connects in Claude Desktop but not in Cursor

Check that the mcp.json config uses the correct protocol version. Cursor and Claude Desktop may support slightly different subsets of the MCP spec. Check the MCP Output panel for the initialize response — if the protocolVersion fields don't match, Cursor may reject the connection. The MCP TypeScript SDK handles version negotiation automatically; if you're using a custom implementation, ensure you respond with the protocolVersion from the client's request.

Tool appears but is never called by the model

Cursor's model decides which tools to call based on the tool's description field. If the description is too generic ("performs document operations") or too technical ("queries the PostgreSQL FTS index"), the model won't recognize when to use it. Make descriptions action-oriented with concrete examples: "Search company documents by keyword. Use this when the user asks to find, look up, or search for specific information in the knowledge base."

Tool call fails with "Request timeout"

Cursor has a timeout on tool call responses (typically 30 seconds). If your handler takes longer than that — a slow database query, an external API call — Cursor times out the request. Fix options: (1) add a timeout to the handler that returns a partial result with an explanation; (2) optimize the slow operation; (3) if the operation is inherently long-running, return a job ID and provide a separate tool to poll for results.

Related pages

• Debugging MCP servers in VS Code
• Debug logging for MCP servers
• MCP Inspector tool
• Debugging stdio transport
• MCP server Cursor integration