Skip to content

fix: Return JSON-RPC protocol errors for unknown tools #1149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

bzsurbhi
Copy link

Return JSON-RPC protocol errors for unknown tools

Motivation and Context

The MCP server was returning tool execution errors for unknown tools instead of proper JSON-RPC protocol errors. This caused issues where Unknown tools were treated as tool execution failures rather than protocol-level errors

Before(Tool execution error):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "Unknown tool: invalid_tool_name"}],
    "isError": true
  }
}

After(Protocol error):

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

Modified the tool call handler in src/mcp/server/lowlevel/server.py to:

  • Check for unknown tools after retrieving from cache
  • Raise McpError with METHOD_NOT_FOUND (-32601) error code for unknown tools

How Has This Been Tested?

  • Added unit test
  • Verified with a server and client example

Breaking Changes

This is a breaking change that corrects the error handling behavior:

  • Unknown tools now return JSON-RPC protocol errors
  • Valid tools that fail during execution still return tool execution errors
  • Input validation errors continue to work as before
  • Warning logs are still generated for unknown tools during lookup

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

@bzsurbhi bzsurbhi marked this pull request as draft July 16, 2025 21:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant