Cursor Tool Call Failed: Causes and Fixes

Quick Answer

A Cursor tool call failed error means Cursor reached your MCP server successfully, sent a tools/call request for a specific tool, and that call did not complete — either rejected before execution, failed inside the server, or terminated by a transport or timeout event. This is not a connection error. The MCP server is running. The specific tool invocation failed.

If the failing tool is Cursor's built-in edit_file tool, use the Cursor edit_file error guide because that failure is usually about file state, workspace permissions, or stale edit context rather than a generic MCP connection problem.

Fastest diagnostic path:

1. Read the exact error message and tool name in Cursor's Output panel.
2. Check whether other tools on the same server still work.
3. Test the failing tool independently with MCP Inspector.
4. Review the MCP server's stderr log for the server-side exception.

60-Second Fix Checklist

• Open Output → MCP in Cursor. Note the exact tool name, arguments sent, and error text.
• Confirm whether other tools on the same server succeed or fail.
• Reload the MCP server in Cursor Settings → MCP to refresh tool definitions.
• Verify all required environment variables are set in the Cursor MCP config (env block).
• Check that required parameters are present and types match the tool schema.
• Inspect the MCP server's own log or stderr output for a stack trace.
• Test the tool independently using MCP Inspector against the same server.
• Confirm no approval was silently denied in Cursor's tool approval UI.
• Check upstream API status if the tool calls an external service.
• If arguments look correct, restart the server process and retry.

Why Cursor Tool Calls Fail

Every tools/call passes through multiple layers. A failure at any layer produces a different symptom.

Find the Exact Tool and Error Message

Before changing anything, collect the complete failure evidence.

In Cursor:

1. Open the Output panel (View → Output).
2. Select the MCP channel from the dropdown.
3. Find the failed tools/call request. It will show:
   • The MCP server name
   • The tool name called
   • The arguments passed (JSON)
   • The error message or JSON-RPC error code returned

In the MCP server logs:

• For stdio servers: stderr output is typically surfaced in Cursor's MCP log or the terminal where you started the server.
• For SSE/HTTP servers: check the server process log or stdout/stderr of the server process.

Key questions to answer before proceeding:

• What is the exact tool name that failed?
• What arguments were sent?
• What was the exact error message or code?
• Do other tools on the same server still work?
• Is this the first call, or did it previously work?

If other tools work, the connection and server runtime are healthy — the failure is tool-specific.

MCP Server Connected but Tool Call Failed

This is the most common source of confusion. Cursor shows the MCP server as connected with a green indicator. Yet a specific tool call fails. Why?

A connected MCP server means:

• The transport (stdio pipe or HTTP/SSE connection) is established.
• initialize completed.
• tools/list returned without error.

None of that guarantees a specific tools/call will succeed. The tool call is a separate JSON-RPC request that triggers execution of a specific function inside the server. That function can fail for entirely independent reasons:

• Tool handler throws an unhandled exception — the server catches it and returns isError: true with a message, or crashes the process entirely.
• Missing environment variable — the tool tries to read process.env.API_KEY and it's undefined, causing a null reference error at runtime.
• Wrong argument shape — Cursor sends arguments based on a cached schema; if the server was updated, the schema may have changed and arguments are now invalid.
• Upstream dependency unavailable — the tool calls an external API or database that is down.
• Filesystem path doesn't exist — the tool tries to read a file using a path that doesn't exist in the server's working directory.
• Permissions insufficient — the server process lacks OS-level permission to perform the requested operation.

The fix depends entirely on which layer failed. Reading the error message and server logs is mandatory before guessing.

Fix Invalid Tool Arguments and Schema Errors

Schema validation failures are the most common cause of cursor mcp tool call failed errors for developers who recently updated a server.

Common argument errors:

How to check the current input schema:

Run MCP Inspector against the same server:

npx @modelcontextprotocol/inspector

Connect to your server, go to the Tools tab, and select the failing tool. The Input Schema panel shows exactly what the server currently expects. Compare this against what Cursor is sending (visible in the Output log).

Stale schema after a server update is particularly tricky. Cursor caches the tools/list response from the last connection. If you modified the tool's inputSchema and restarted the server without reloading the connection in Cursor, Cursor may send arguments that no longer match. Always reload the MCP server in Cursor Settings → MCP after updating tool schemas.

Unknown Tool or Tool Not Found

If the error references an unknown tool or the call fails with JSON-RPC error -32601 (Method Not Found), the tool name Cursor is trying to call does not exist in the server's current tools/list.

This is different from a failed tool call — the server never executed anything because it couldn't find the requested tool.

Common causes:

• Tool was renamed or removed in a server update, but Cursor's tool list wasn't refreshed.
• Typo in a manually configured tool name.
• Server started with different configuration (wrong profile, wrong env) that omits the tool.
• Multiple MCP servers registered with overlapping tool names — Cursor routed the call to the wrong server.

Fix: Reload the MCP server in Cursor settings to force a fresh tools/list. Confirm the tool appears in the refreshed list. If it doesn't, check the server startup logs to see which tools registered successfully.

For detailed diagnosis of unknown tool errors and -32601 specifically, see our guides on unknown MCP tool errors and MCP Error -32601 Method Not Found.

Tool Call Failed Because of Permissions or Approvals

Cursor operates an approval layer for tool calls. If a tool is classified as requiring explicit user approval, Cursor will prompt before executing. If that prompt is dismissed or silently denied, the tool call fails before reaching the server.

Cursor-level approval failures:

• The approval prompt appeared and was rejected.
• The tool is flagged as requiring human review and approval is disabled in settings.
• Policy or governance settings block the tool category.

OS-level permission failures (inside the server):

• The MCP server process tries to read/write a filesystem path it doesn't have access to.
• The server tries to execute a shell command but lacks execute permission.
• The server attempts a network connection blocked by firewall rules.
• The server runs as a restricted user without access to required resources.

Diagnosis:

• If the error appears immediately without reaching the server: check Cursor's approval UI and settings.
• If the error comes back from the server with a permission-related message: check the server process's OS permissions and the specific path or resource it tried to access.

Do not work around security controls by running the server as root or disabling approval workflows. Instead, grant the minimum necessary permissions for the specific paths and operations the tool legitimately needs.

Tool Call Failed with Connection Closed or Timeout

If the tool call terminates with a connection closed or timeout error rather than a structured error response, the failure occurred at the transport layer — not inside the tool handler.

Connection Closed during a tool call typically means:

• The server process crashed while executing the tool (check stderr for the exception).
• The stdio pipe was terminated (server process exited).
• For SSE/HTTP: the server closed the connection before sending a response.

Request Timed Out means:

• The tool's execution exceeded Cursor's per-call timeout.
• A slow upstream API, large file operation, or blocking I/O caused the delay.
• A proxy or network gateway between Cursor and an HTTP-based MCP server closed the idle connection.

How to distinguish them:

• If the server process is gone after the failure: crash.
• If the server is still running but the call took a long time: timeout.
• Check the exact JSON-RPC error code in the Cursor MCP log.

For MCP Error -32000 (Connection Closed) diagnosis, see the complete -32000 troubleshooting guide. For timeout-specific fixes including upstream API slowness and transport-level configuration, see the MCP Error -32001 Request Timed Out guide.

Tool Call Failed Because the MCP Server Crashed

A server crash during tool execution is distinct from a server that fails to start. The server was running, accepted the tools/call, and then the process died.

Root causes:

• Unhandled exception or promise rejection inside the tool handler with no try/catch.
• Tool attempts to access undefined (e.g., a missing env variable) mid-execution.
• Out-of-memory error triggered by processing large inputs.
• Missing native dependency (e.g., a Node.js addon that wasn't compiled for the current platform).
• stdout contamination (critical for stdio servers): the tool handler calls console.log() or any library that writes to stdout, corrupting the JSON-RPC framing. Only console.error() / stderr is safe for diagnostic output in stdio servers.

Diagnosis steps:

1. Check the server's stderr output immediately after the crash.
2. Look for an uncaught exception message and stack trace.
3. Confirm the server process PID is no longer running after the failure.
4. If no output appears, add explicit error boundaries in the tool handler:

server.tool("my-tool", schema, async (args) => {
  try {
    // tool implementation
    return { content: [{ type: "text", text: result }] };
  } catch (err) {
    // Return a structured error instead of crashing
    return {
      content: [{ type: "text", text: `Tool failed: ${err.message}` }],
      isError: true
    };
  }
});

Returning isError: true with a message allows the server to stay alive and gives Cursor a structured error to surface rather than a connection drop.

One Tool Fails but Other Tools Work

This pattern is definitive: if other tools on the same server succeed, the MCP server, transport, and authentication are all working. The failure is isolated to the specific tool.

Diagnostic flow:

1. Check the tool's own implementation — does it have error handling? Does it depend on environment variables that might be missing?
2. Review the specific arguments — are all required parameters present? Are types correct for this specific tool (different tools have different schemas)?
3. Check tool-specific dependencies — some tools require additional packages, credentials, or services that other tools on the same server don't use.
4. Test with MCP Inspector — call the failing tool directly with the same arguments Cursor is sending. If it fails in Inspector too, the bug is in the tool code. If it succeeds, compare the environment and arguments between the two contexts.
5. Check for upstream service issues — if this tool calls a specific external API, check that service's status independently.
6. Temporarily simplify the input — call the tool with minimal valid arguments to isolate whether the failure is input-dependent.

Tool Works Outside Cursor but Fails in Cursor

This pattern indicates an environment difference between how you run the server manually and how Cursor runs it.

Verifying environment variables in Cursor MCP config:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/server/index.js"],
      "env": {
        "API_KEY": "your-key-here",
        "DATABASE_URL": "postgresql://...",
        "NODE_ENV": "production"
      }
    }
  }
}

Use absolute paths for both the command and any file arguments. Never rely on ~ expansion in MCP config — it is not guaranteed to resolve correctly.

How to Read Cursor Tool Call Errors and Logs

Where to look:

• Cursor Output panel (View → Output → MCP): Shows JSON-RPC messages between Cursor and each MCP server. Look for tools/call requests and their responses, including error codes and messages.
• MCP server stderr: For stdio-based servers, stderr is captured and typically shown in the Cursor MCP output. For HTTP/SSE servers, check the server process terminal or log file.
• Cursor Developer Tools (Help → Toggle Developer Tools): The console and network panels can reveal additional Cursor-internal errors not shown in the Output panel.

What to record before making changes:

• Exact tool name from the failed request
• Full argument payload sent
• Complete error message and any JSON-RPC error code
• Whether other tools on the same server succeed
• Server stderr output at the time of failure
• Any pattern (always fails, fails on first call, fails after N calls)

Collect this information first. Changing configuration before understanding the failure often masks the real cause.

Debug with MCP Inspector

MCP Inspector is the definitive tool for isolating whether a failure is Cursor-specific or present in the server itself.

npx @modelcontextprotocol/inspector

Diagnostic steps:

1. Connect to the same server using the same command and environment variables you use in Cursor.
2. Go to the Tools tab and confirm the failing tool appears in the list. If it doesn't, the server has a registration problem independent of Cursor.
3. Inspect the tool's Input Schema — this is the current schema, not Cursor's cached version. Compare it to what Cursor is sending.
4. Call the failing tool with the same arguments Cursor was using. Observe the response.
   • If it fails in Inspector: the bug is in the server. Check Inspector's error and the server's stderr.
   • If it succeeds in Inspector: the failure is Cursor-specific. Compare environments, credentials, and arguments.
5. Try minimal arguments — remove all optional fields and call with only required fields. If it succeeds, add fields back one at a time to isolate the bad input.
6. Inspect the raw response — Inspector shows the full JSON-RPC response including isError, content, and any error metadata.

You can also use MCPForge's online MCP server testing tool to verify server behavior without a local Inspector setup.

Comprehensive Troubleshooting Table

How to Confirm the Fix

After applying a fix, verify each layer:

• MCP server shows as connected in Cursor settings with no error indicator.
• The expected tool appears in the server's tool list (reload first).
• Tool schema in Inspector matches what you expect (no stale definitions).
• A test tool call with minimal valid arguments completes without error.
• The response contains expected content and isError is absent or false.
• Cursor Output log shows no repeated error messages for the tool.
• Server stderr shows no exceptions or warnings related to the call.
• Subsequent calls (including edge-case inputs) continue to succeed.

How to Prevent Cursor Tool Call Failures

Server-side best practices:

• Wrap every tool handler in a try/catch block and return isError: true with a descriptive message rather than letting exceptions crash the server.
• Never write to stdout in stdio-based MCP servers — use stderr for all diagnostic output.
• Validate all required environment variables at startup, not at call time. Fail fast with a clear error message if credentials are missing.
• Use absolute paths for all file operations. Never assume a working directory.
• Keep inputSchema definitions accurate and up to date. Add descriptions to every field.
• Handle upstream API errors gracefully — return a structured error response rather than propagating raw HTTP errors.

Configuration best practices:

• Always specify absolute paths for the server command and file arguments in Cursor's MCP config.
• Explicitly list every required environment variable in the env block — do not rely on shell inheritance.
• After updating a server, reload it in Cursor settings before expecting new tools or changed schemas to work.
• Test new tool implementations in MCP Inspector before connecting them to Cursor.

Operational hygiene:

• Monitor for repeated tool call failures in logs — they often signal a degraded upstream dependency before it becomes a complete outage.
• Keep MCP server dependencies pinned to verified versions. Runtime dependency changes cause subtle tool failures that are hard to diagnose.
• For servers calling external APIs, implement exponential backoff and surface rate limit information in error messages.

For a broader reference on MCP error codes and what they mean, see the MCP Error Codes reference. If the tool call failure is actually a server that won't connect at all, see the Cursor MCP Server Failed to Connect guide.

Official Sources

• MCP tools specification - official behavior for tools/list, tools/call, tool input schemas, and tool results.
• MCP base protocol overview - official JSON-RPC request, response, notification, and error structure used by MCP.
• JSON-RPC 2.0 specification - authoritative error-code and method-call semantics behind MCP protocol errors.
• Cursor status - official service status page for ruling out platform outages.