Skip to content

Conversation

@DePasqualeOrg
Copy link

While developing my Swift SDK for MCP, I encountered the following MCP spec compliance issue in the Python SDK:

When an unknown tool is called, it throws a ToolError, which is caught by the server's exception handler and converted to a response with isError: true.

The spec distinguishes between protocol errors and tool execution errors:

Protocol Errors:

  1. Protocol Errors: Standard JSON-RPC errors for issues like:
    • Unknown tools
    • Invalid arguments
    • Server errors

Tool Execution Errors:

  1. Tool Execution Errors: Reported in tool results with isError: true:
    • API failures
    • Invalid input data
    • Business logic errors

Protocol error example for unknown tool:

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

The same issue applies to prompts and resources. Per the spec:

  • Unknown prompts should return -32602 (INVALID_PARAMS): spec reference
  • Unknown resources should return -32002 (RESOURCE_NOT_FOUND): spec reference

Changes

  • ToolManager: Raises McpError with INVALID_PARAMS (-32602) for unknown tools
  • PromptManager: Raises McpError with INVALID_PARAMS (-32602) for unknown prompts
  • ResourceManager: Raises McpError with RESOURCE_NOT_FOUND (-32002) for unknown resources
  • Added RESOURCE_NOT_FOUND constant to mcp.types

How Has This Been Tested?

I updated the tests to check for the correct error handling.

Breaking Changes

Users who expected the incorrect error handling may need to change their code.

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

@DePasqualeOrg DePasqualeOrg changed the title Fix unknown tool/prompt/resource error handling fix: correct unknown tool/prompt/resource error handling Jan 15, 2026
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