Report Skills handler-output faults as INTERNAL_ERROR, not INVALID_PARAMS

A non-conformant result from a `list_skills`/`get_skill`/`read_directory`
handler (or a `get_skill` URI mismatch) is a server-side bug, not a bad
caller request, so -32603 is the correct code rather than -32602. Log the
real cause server-side and return a generic message, mirroring the runner's
existing handling of invalid handler results. Input validation
(`_require_skill_md_uri`, `_require_directory_uri`, params) stays -32602.

Author: vijay

src/mcp/server/skills.py

@@ -28,10 +28,11 @@ async def get_skill(ctx, params):
 
 from __future__ import annotations
 
+import logging
 from collections.abc import Awaitable, Callable, Sequence
 from typing import Any
 
-from mcp_types.jsonrpc import INVALID_PARAMS
+from mcp_types.jsonrpc import INTERNAL_ERROR, INVALID_PARAMS
 from mcp_types.version import MODERN_PROTOCOL_VERSIONS
 
 from mcp.server.context import HandlerResult, ServerRequestContext
@@ -57,6 +58,8 @@ async def get_skill(ctx, params):
 
 __all__ = ["Skills"]
 
+logger = logging.getLogger(__name__)
+
 ListSkillsHandler = Callable[[ServerRequestContext[Any, Any], ListSkillsParams], Awaitable[ListSkillsResult]]
 GetSkillHandler = Callable[[ServerRequestContext[Any, Any], GetSkillParams], Awaitable[GetSkillResult]]
 ReadDirectoryHandler = Callable[[ServerRequestContext[Any, Any], ReadDirectoryParams], Awaitable[ReadDirectoryResult]]
@@ -102,24 +105,22 @@ async def _handle_list(self, ctx: ServerRequestContext[Any, Any], params: ListSk
         result = await self._list_skills(ctx, params)
         try:
             validate_list_result(result)
-        except ValueError as exc:
-            raise MCPError(
-                code=INVALID_PARAMS, message=f"list_skills handler returned an invalid result: {exc}"
-            ) from exc
+        except ValueError:
+            logger.exception("list_skills handler returned an invalid result")
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result") from None
         return _finalize_cacheable(result, ctx.protocol_version)
 
     async def _handle_get(self, ctx: ServerRequestContext[Any, Any], params: GetSkillParams) -> HandlerResult:
         _require_skill_md_uri(params.uri)
         result = await self._get_skill(ctx, params)
         if result.skill.uri != params.uri:
-            raise MCPError(
-                code=INVALID_PARAMS,
-                message=f"get_skill handler returned {result.skill.uri!r} for requested {params.uri!r}",
-            )
+            logger.error("get_skill handler returned %r for requested %r", result.skill.uri, params.uri)
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result")
         try:
             validate_skill(result.skill)
-        except ValueError as exc:
-            raise MCPError(code=INVALID_PARAMS, message=f"get_skill handler returned an invalid result: {exc}") from exc
+        except ValueError:
+            logger.exception("get_skill handler returned an invalid result")
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result") from None
         return result
 
     async def _handle_read_directory(
@@ -130,10 +131,9 @@ async def _handle_read_directory(
         result = await self._read_directory(ctx, params)
         try:
             validate_directory_result(params.uri, result)
-        except ValueError as exc:
-            raise MCPError(
-                code=INVALID_PARAMS, message=f"read_directory handler returned an invalid result: {exc}"
-            ) from exc
+        except ValueError:
+            logger.exception("read_directory handler returned an invalid result")
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result") from None
         return result
 
 

tests/server/test_skills.py

@@ -11,7 +11,7 @@
 
 import pytest
 from inline_snapshot import snapshot
-from mcp_types import INVALID_PARAMS, METHOD_NOT_FOUND, Resource
+from mcp_types import INTERNAL_ERROR, INVALID_PARAMS, METHOD_NOT_FOUND, Resource
 from pydantic import BaseModel, ConfigDict
 
 from mcp.client.client import Client
@@ -135,8 +135,8 @@ async def private_list(ctx: ServerRequestContext[Any, Any], params: ListSkillsPa
 
 async def test_skills_list_rejects_a_handler_result_with_an_invalid_skill() -> None:
     """SDK-defined: a `list_skills` handler bug (a non-conformant skill entry) is caught
-    before it reaches the client, as an Invalid params error rather than a silently
-    non-conformant listing."""
+    before it reaches the client, as an Internal error — the fault is the server's, not the
+    caller's params — rather than a silently non-conformant listing."""
 
     async def bad_list(ctx: ServerRequestContext[Any, Any], params: ListSkillsParams) -> ListSkillsResult:
         return ListSkillsResult(
@@ -147,7 +147,7 @@ async def bad_list(ctx: ServerRequestContext[Any, Any], params: ListSkillsParams
     async with Client(server) as client:
         with pytest.raises(MCPError) as exc_info:
             await client.session.send_request(ListSkillsRequest(), ListSkillsResult)
-    assert exc_info.value.code == INVALID_PARAMS
+    assert exc_info.value.code == INTERNAL_ERROR
 
 
 async def test_skills_get_returns_the_matching_skill() -> None:
@@ -196,7 +196,7 @@ async def test_skills_get_rejects_a_uri_that_does_not_end_in_skill_md() -> None:
 
 async def test_skills_get_rejects_a_handler_that_returns_a_mismatched_uri() -> None:
     """SDK-defined: a `get_skill` handler bug (returning the wrong skill) is caught before
-    it reaches the client, as an Invalid params error rather than a silently wrong answer."""
+    it reaches the client, as an Internal error rather than a silently wrong answer."""
 
     async def wrong_skill(ctx: ServerRequestContext[Any, Any], params: GetSkillParams) -> GetSkillResult:
         return GetSkillResult(skill=_git_workflow_skill())
@@ -207,12 +207,12 @@ async def wrong_skill(ctx: ServerRequestContext[Any, Any], params: GetSkillParam
             await client.session.send_request(
                 GetSkillRequest(params=GetSkillParams(uri="skill://other/SKILL.md")), GetSkillResult
             )
-    assert exc_info.value.code == INVALID_PARAMS
+    assert exc_info.value.code == INTERNAL_ERROR
 
 
 async def test_skills_get_rejects_a_matching_but_non_conformant_skill() -> None:
     """SDK-defined: a `get_skill` handler bug (a non-conformant skill body, distinct from a
-    URI mismatch) is caught the same way, as an Invalid params error."""
+    URI mismatch) is caught the same way, as an Internal error."""
 
     async def bad_skill(ctx: ServerRequestContext[Any, Any], params: GetSkillParams) -> GetSkillResult:
         return GetSkillResult(
@@ -223,7 +223,7 @@ async def bad_skill(ctx: ServerRequestContext[Any, Any], params: GetSkillParams)
     async with Client(server) as client:
         with pytest.raises(MCPError) as exc_info:
             await client.session.send_request(GetSkillRequest(params=GetSkillParams(uri=_SKILL_URI)), GetSkillResult)
-    assert exc_info.value.code == INVALID_PARAMS
+    assert exc_info.value.code == INTERNAL_ERROR
 
 
 async def test_missing_uri_param_is_rejected_before_the_handler_runs() -> None:
@@ -277,6 +277,9 @@ async def test_directory_read_rejects_a_trailing_slash_uri() -> None:
 
 
 async def test_directory_read_rejects_a_handler_result_with_a_grandchild() -> None:
+    """SDK-defined: a `read_directory` handler bug (a non-direct child) is a server fault,
+    surfaced as an Internal error, not the caller's Invalid params."""
+
     async def bad_directory(ctx: ServerRequestContext[Any, Any], params: ReadDirectoryParams) -> ReadDirectoryResult:
         return ReadDirectoryResult(resources=[Resource(uri="skill://git-workflow/a/b/c.md", name="c.md")])
 
@@ -288,4 +291,4 @@ async def bad_directory(ctx: ServerRequestContext[Any, Any], params: ReadDirecto
             await client.session.send_request(
                 ReadDirectoryRequest(params=ReadDirectoryParams(uri="skill://git-workflow")), ReadDirectoryResult
             )
-    assert exc_info.value.code == INVALID_PARAMS
+    assert exc_info.value.code == INTERNAL_ERROR