MCP Tool Call Failed: How to Fix It (Claude, Claude Code, Cursor, VS Code)

"Tool call failed" means the MCP server is connected, but one specific call did not succeed. Either the request itself was rejected (a protocol error, such as an unknown tool or bad arguments) or the tool ran and reported a problem (a tool execution error, such as an API failure or invalid date). The fastest fix is to copy the tool name and arguments, run the same call in the MCP Inspector, and read the exact error it returns.

Checked against: the MCP 2026-07-28 tools specification, Claude's connector troubleshooting page, the MCP Inspector docs, Cursor's MCP docs and the Claude Code MCP docs on 2 November 2026. eSEOspace did not reproduce failures in each client.

What this error means

The 2026-07-28 tools specification splits failures in two.

Protocol errors cover "unknown tool," "malformed requests" and "server errors." They come back as standard JSON-RPC errors, for example:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name"
  }
}

Tool execution errors cover "API failures," "input validation errors" and "business logic errors." They come back as a normal result with isError: true and a text message. The spec says clients "SHOULD provide tool execution errors to language models to enable self-correction."

So a failed call is not a broken connection. Claude's troubleshooting page says the same: "A failed tool call isn't a connection failure."

Quick fix

1. Read the error text. It often says exactly what is wrong, such as a missing field or an expired record.
2. Replay the call in the Inspector. The Inspector docs show a CLI form:

npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http \
  --method tools/call --tool-name get_weather --tool-arg city=Boston --format json

For a local server, put its command after --cli instead of the URL.

1. Compare the arguments with the tool's input schema from tools/list. Wrong types, wrong date formats and missing required fields are common.
2. Check permissions. If the tool calls an outside API, your account may lack access to that record or action.
3. Check the server logs at the time of the failure. Claude's troubleshooting page also asks whether the failure "affects every user of your connector or one account."
4. Retry with corrected input, or tell the model what was wrong in your next message.

Fix by client / OS

Claude (claude.ai and Desktop connectors)

"Unexpected error while invoking tool," followed by the tool name, means "Claude's tool call reached your server, and your server returned an error result for it," per Claude's troubleshooting page. There is no ofid_ reference ID for tool failures. To report one, include the tool name, the time of the failure in UTC, and the connector URL.

Claude Code

The Claude Code MCP docs say Claude Code shows a warning when tool output exceeds 10,000 tokens and limits it to 25,000 tokens by default. Raise the limit with MAX_MCP_OUTPUT_TOKENS=50000. Long-running tools can hit the tool timeout; set MCP_TOOL_TIMEOUT or a per-server timeout.

Cursor

Cursor's MCP docs say failed tool calls are marked as failed in chat, and you can retry or check the logs. Cursor asks for approval by default, and you can expand a call to see its arguments, which helps spot bad input.

VS Code

Use MCP: List Servers > Show Output to read the server's side. The VS Code MCP page notes that a running server does not guarantee its tools are available to the current session.

Where to find the logs

Map any JSON-RPC code you see with the MCP error code lookup.

If it still fails

• Error code -32602 on every call. See invalid params -32602.
• The tool does not exist. The model may be using an old name. Refresh the tool list or see method not found -32601.
• The call hangs then fails. See request timed out.
• The server drops during the call. See Connection closed.
• You build the server. Return helpful isError messages. The MCP tool errors reference and error handling lesson show how.

If a vendor tool keeps failing in ways that hurt your team's work, an MCP readiness audit can decide whether to replace it or wrap it.

Frequently asked questions