Type the MCPServer handler pipeline: tool/resource/prompt return types

The chain from user @tool()-decorated functions through to CallToolResult is typed as Any end-to-end, hiding a wrong public return type and dead code.

Tool call chain

FuncMetadata.convert_result() returns exactly three shapes:

• CallToolResult (when the user returned one directly)
• Sequence[ContentBlock] (unstructured)
• tuple[Sequence[ContentBlock], dict[str, Any]] (unstructured + structured)

But every step of the chain is -> Any:

• FuncMetadata.convert_result() — -> Any
• Tool.run() — -> Any
• ToolManager.call_tool() — -> Any
• MCPServer.call_tool() — declared -> Sequence[ContentBlock] | dict[str, Any], wrong — never returns dict

Root cause: the convert_result: bool flag on Tool.run() / ToolManager.call_tool() toggles the return type, which is unrepresentable. The False path isn't used in production (only server.py:405, always True).

Symptoms:

• Dead code + TODO acknowledging the wrong type at server.py:317-324
• # type: ignore[arg-type] shoving tuple elements into CallToolResult at server.py:314-315

Prompt / Resource

• PromptResult already includes Awaitable, but Prompt.fn is typed Callable[..., PromptResult | Awaitable[PromptResult]] — doubly wrapped
• ResourceTemplate.matches() returns dict[str, Any] | None but values are always str (regex groupdict + unquote)

User-facing return types

What you can return from @tool() is undocumented. A strict bound is impossible (_convert_to_content() ends with pydantic_core.to_json(fallback=str) — everything works), but the docstrings should enumerate what gets first-class handling (str/primitives/BaseModel/ContentBlock/Image/Audio/CallToolResult/list/tuple) vs what gets JSON-dumped.

Related

• #1207 — excessive generics (reason to not introduce Tool[ReturnT]; a TypeAlias for the converted result is sufficient)
• #2153 — handler error semantics
• #2201 — Tasks support (adds CreateTaskResult to the converted-result union)

_{AI Disclaimer}

Start with FuncMetadata.convert_result(), Tool.run(), ToolManager.call_tool(), and MCPServer.call_tool() to trace the tool return chain and the convert_result flag. Then inspect Prompt.fn, PromptResult, and ResourceTemplate.matches() for the stated annotation mismatches. Done means the handler pipeline has accurate public types, dead or incorrect typing paths are addressed, and user-facing return handling is documented.