Fix unknown tool/prompt/resource error handling

Author: DePasqualeOrg

src/mcp/server/fastmcp/prompts/manager.py

@@ -6,6 +6,8 @@
 
 from mcp.server.fastmcp.prompts.base import Message, Prompt
 from mcp.server.fastmcp.utilities.logging import get_logger
+from mcp.shared.exceptions import McpError
+from mcp.types import INVALID_PARAMS, ErrorData
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -55,6 +57,7 @@ async def render_prompt(
         """Render a prompt by name with arguments."""
         prompt = self.get_prompt(name)
         if not prompt:
-            raise ValueError(f"Unknown prompt: {name}")
+            # Unknown prompt is a protocol error per MCP spec
+            raise McpError(ErrorData(code=INVALID_PARAMS, message=f"Unknown prompt: {name}"))
 
         return await prompt.render(arguments, context=context)

src/mcp/server/fastmcp/resources/resource_manager.py

@@ -10,7 +10,8 @@
 from mcp.server.fastmcp.resources.base import Resource
 from mcp.server.fastmcp.resources.templates import ResourceTemplate
 from mcp.server.fastmcp.utilities.logging import get_logger
-from mcp.types import Annotations, Icon
+from mcp.shared.exceptions import McpError
+from mcp.types import RESOURCE_NOT_FOUND, Annotations, ErrorData, Icon
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -85,8 +86,12 @@ async def get_resource(
         self,
         uri: AnyUrl | str,
         context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None,
-    ) -> Resource | None:
-        """Get resource by URI, checking concrete resources first, then templates."""
+    ) -> Resource:
+        """Get resource by URI, checking concrete resources first, then templates.
+
+        Raises:
+            McpError: If the resource is not found (RESOURCE_NOT_FOUND error code).
+        """
         uri_str = str(uri)
         logger.debug("Getting resource", extra={"uri": uri_str})
 
@@ -102,7 +107,8 @@ async def get_resource(
                 except Exception as e:  # pragma: no cover
                     raise ValueError(f"Error creating resource from template: {e}")
 
-        raise ValueError(f"Unknown resource: {uri}")
+        # Resource not found is a protocol error per MCP spec
+        raise McpError(ErrorData(code=RESOURCE_NOT_FOUND, message=f"Unknown resource: {uri}"))
 
     def list_resources(self) -> list[Resource]:
         """List all registered resources."""

src/mcp/server/fastmcp/server.py

@@ -44,7 +44,16 @@
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from mcp.server.transport_security import TransportSecuritySettings
 from mcp.shared.context import LifespanContextT, RequestContext, RequestT
-from mcp.types import Annotations, ContentBlock, GetPromptResult, Icon, ToolAnnotations
+from mcp.shared.exceptions import McpError
+from mcp.types import (
+    INVALID_PARAMS,
+    Annotations,
+    ContentBlock,
+    ErrorData,
+    GetPromptResult,
+    Icon,
+    ToolAnnotations,
+)
 from mcp.types import Prompt as MCPPrompt
 from mcp.types import PromptArgument as MCPPromptArgument
 from mcp.types import Resource as MCPResource
@@ -964,14 +973,16 @@ async def get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -
         try:
             prompt = self._prompt_manager.get_prompt(name)
             if not prompt:
-                raise ValueError(f"Unknown prompt: {name}")
+                raise McpError(ErrorData(code=INVALID_PARAMS, message=f"Unknown prompt: {name}"))
 
             messages = await prompt.render(arguments, context=self.get_context())
 
             return GetPromptResult(
                 description=prompt.description,
                 messages=pydantic_core.to_jsonable_python(messages),
             )
+        except McpError:
+            raise
         except Exception as e:
             logger.exception(f"Error getting prompt {name}")
             raise ValueError(str(e))

src/mcp/server/fastmcp/tools/tool_manager.py

@@ -7,7 +7,8 @@
 from mcp.server.fastmcp.tools.base import Tool
 from mcp.server.fastmcp.utilities.logging import get_logger
 from mcp.shared.context import LifespanContextT, RequestT
-from mcp.types import Icon, ToolAnnotations
+from mcp.shared.exceptions import McpError
+from mcp.types import INVALID_PARAMS, ErrorData, Icon, ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -88,6 +89,7 @@ async def call_tool(
         """Call a tool by name with arguments."""
         tool = self.get_tool(name)
         if not tool:
-            raise ToolError(f"Unknown tool: {name}")
+            # Unknown tool is a protocol error per MCP spec
+            raise McpError(ErrorData(code=INVALID_PARAMS, message=f"Unknown tool: {name}"))
 
         return await tool.run(arguments, context=context, convert_result=convert_result)

src/mcp/server/lowlevel/server.py

@@ -600,6 +600,10 @@ async def handler(req: types.CallToolRequest):
                     # Re-raise UrlElicitationRequiredError so it can be properly handled
                     # by _handle_request, which converts it to an error response with code -32042
                     raise
+                except McpError:
+                    # Re-raise McpError as protocol error
+                    # (e.g., unknown tool returns INVALID_PARAMS per MCP spec)
+                    raise
                 except Exception as e:
                     return self._make_error_result(str(e))
 

src/mcp/types/__init__.py

@@ -192,6 +192,7 @@
     METHOD_NOT_FOUND,
     PARSE_ERROR,
     REQUEST_TIMEOUT,
+    RESOURCE_NOT_FOUND,
     URL_ELICITATION_REQUIRED,
     ErrorData,
     JSONRPCError,
@@ -404,6 +405,7 @@
     "METHOD_NOT_FOUND",
     "PARSE_ERROR",
     "REQUEST_TIMEOUT",
+    "RESOURCE_NOT_FOUND",
     "URL_ELICITATION_REQUIRED",
     "ErrorData",
     "JSONRPCError",

src/mcp/types/jsonrpc.py

@@ -43,6 +43,8 @@ class JSONRPCResponse(BaseModel):
 # SDK error codes
 CONNECTION_CLOSED = -32000
 REQUEST_TIMEOUT = -32001
+RESOURCE_NOT_FOUND = -32002
+"""Error code indicating that a requested resource was not found."""
 
 # Standard JSON-RPC error codes
 PARSE_ERROR = -32700

tests/issues/test_141_resource_templates.py

@@ -2,7 +2,9 @@
 
 from mcp import Client
 from mcp.server.fastmcp import FastMCP
+from mcp.shared.exceptions import McpError
 from mcp.types import (
+    RESOURCE_NOT_FOUND,
     ListResourceTemplatesResult,
     TextResourceContents,
 )
@@ -53,12 +55,14 @@ def get_user_profile_missing(user_id: str) -> str:  # pragma: no cover
     assert result_list[0].content == "Post 456 by user 123"
     assert result_list[0].mime_type == "text/plain"
 
-    # Verify invalid parameters raise error
-    with pytest.raises(ValueError, match="Unknown resource"):
+    # Verify invalid parameters raise protocol error
+    with pytest.raises(McpError, match="Unknown resource") as exc_info:
         await mcp.read_resource("resource://users/123/posts")  # Missing post_id
+    assert exc_info.value.error.code == RESOURCE_NOT_FOUND
 
-    with pytest.raises(ValueError, match="Unknown resource"):
+    with pytest.raises(McpError, match="Unknown resource") as exc_info:
         await mcp.read_resource("resource://users/123/posts/456/extra")  # Extra path component
+    assert exc_info.value.error.code == RESOURCE_NOT_FOUND
 
 
 @pytest.mark.anyio

tests/server/fastmcp/prompts/test_manager.py

@@ -2,6 +2,8 @@
 
 from mcp.server.fastmcp.prompts.base import Prompt, TextContent, UserMessage
 from mcp.server.fastmcp.prompts.manager import PromptManager
+from mcp.shared.exceptions import McpError
+from mcp.types import INVALID_PARAMS
 
 
 class TestPromptManager:
@@ -89,10 +91,11 @@ def fn(name: str) -> str:
 
     @pytest.mark.anyio
     async def test_render_unknown_prompt(self):
-        """Test rendering a non-existent prompt."""
+        """Test rendering a non-existent prompt raises protocol error."""
         manager = PromptManager()
-        with pytest.raises(ValueError, match="Unknown prompt: unknown"):
+        with pytest.raises(McpError, match="Unknown prompt: unknown") as exc_info:
             await manager.render_prompt("unknown")
+        assert exc_info.value.error.code == INVALID_PARAMS
 
     @pytest.mark.anyio
     async def test_render_prompt_with_missing_args(self):

tests/server/fastmcp/resources/test_resource_manager.py

@@ -5,6 +5,8 @@
 from pydantic import AnyUrl
 
 from mcp.server.fastmcp.resources import FileResource, FunctionResource, ResourceManager, ResourceTemplate
+from mcp.shared.exceptions import McpError
+from mcp.types import RESOURCE_NOT_FOUND
 
 
 @pytest.fixture
@@ -111,10 +113,11 @@ def greet(name: str) -> str:
 
     @pytest.mark.anyio
     async def test_get_unknown_resource(self):
-        """Test getting a non-existent resource."""
+        """Test getting a non-existent resource raises protocol error."""
         manager = ResourceManager()
-        with pytest.raises(ValueError, match="Unknown resource"):
+        with pytest.raises(McpError, match="Unknown resource") as exc_info:
             await manager.get_resource(AnyUrl("unknown://test"))
+        assert exc_info.value.error.code == RESOURCE_NOT_FOUND
 
     def test_list_resources(self, temp_file: Path):
         """Test listing all resources."""