Your MCP server tool call failed:

Error: Tool call failed: invalid parameters

Or the tool returned unexpected results. Here is how to fix it.

Fix 1: Check tool definition

The tool must be properly defined:

// Correct tool definition
{
  name: "search",
  description: "Search for files",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Search query"
      },
      limit: {
        type: "number",
        description: "Max results",
        default: 10
      }
    },
    required: ["query"]
  }
}

Fix 2: Validate parameters

Check parameter types match:

// Server-side validation
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  // Validate required params
  if (!args.query || typeof args.query !== 'string') {
    return {
      content: [{ type: 'text', text: 'Error: query must be a string' }],
      isError: true
    };
  }
  
  // Process tool call
  const result = await searchFiles(args.query, args.limit || 10);
  return { content: [{ type: 'text', text: result }] };
});

Fix 3: Fix JSON schema

Ensure schema is valid:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    }
  },
  "required": ["query"],
  "additionalProperties": false
}

Fix 4: Handle errors gracefully

Return proper error responses:

try {
  const result = await processToolCall(args);
  return {
    content: [{ type: 'text', text: JSON.stringify(result) }]
  };
} catch (error) {
  return {
    content: [{ type: 'text', text: `Error: ${error.message}` }],
    isError: true
  };
}

Fix 5: Check MCP protocol version

Ensure compatibility:

# Check MCP SDK version
npm list @modelcontextprotocol/sdk

# Update if needed
npm update @modelcontextprotocol/sdk

Fix 6: Test tool directly

Bypass Claude Code to test:

# Call MCP server directly
curl -X POST http://localhost:3000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name":"search","arguments":{"query":"test"}}'

Still not working?

1. Check server logs — Look for errors
2. Validate JSON — Ensure responses are valid JSON
3. Check tool name — Must match exactly
4. Test with minimal params — Simplify the call

FAQ

Why is my MCP tool call failing?

The most common causes are: incorrect tool name (must match exactly), invalid parameters (wrong types or missing required fields), or the MCP server has errors. Check server logs and test the tool directly with curl.

How do I test an MCP tool without Claude Code?

Use curl to call the MCP server directly: curl -X POST http://localhost:PORT/tools/call -H "Content-Type: application/json" -d '{"name":"tool-name","arguments":{...}}'. This bypasses Claude Code and lets you debug the server independently.

Can I see what parameters a tool expects?

Yes. Check the tool’s inputSchema in the MCP server code or call http://localhost:PORT/tools to list all tools with their schemas.

Related: MCP Complete Developer Guide · MCP Server Connection Refused Fix · What is MCP? · Best MCP Servers 2026