Skip to content

Commit 50c6823

Browse files
cliffhallclaude
andcommitted
feat(fetch): build on MCPServer; an unknown tool is a -32602 error (modelcontextprotocol#5174)
The fetch server moves from the SDK's low-level Server, with its SDK v1 compatibility wrappers, to the high-level MCPServer, so this reference server shows the API new servers should use: - The `fetch` tool and prompt are decorated functions. Their type hints and Field descriptions are the input schema and the prompt's arguments, and MCPServer validates calls against them. The non-URL parameters are strict, so a string is not coerced to the integer or boolean the schema declares. - Anticipated failures (robots.txt refusal, connection failure, HTTP error status, refused private address, unusable proxy) raise ToolError, which MCPServer returns as an isError result prefixed "Error executing tool fetch: ". - An unknown tool is now a JSON-RPC -32602 protocol error, as both spec revisions require. MCPServer still answers it with isError (python-sdk#3659), so a middleware rejects the name first; it also keeps -32602 for an unknown prompt and a prompt call without `url`, which MCPServer would answer with -32603. - subscriptions=False: the lists never change, so the 2026-07-28 era advertises listChanged: false. - The hand-rolled jsonschema validation and isError folding are gone, and so is the direct jsonschema dependency. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 400777f commit 50c6823

7 files changed

Lines changed: 288 additions & 278 deletions

File tree

‎src/fetch/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,14 @@ The fetch tool will truncate the response, but by using the `start_index` argume
3131
- Arguments:
3232
- `url` (string, required): URL to fetch
3333

34+
### Errors
35+
36+
- A failed fetch (a robots.txt refusal, an unreachable page, an HTTP error status, a refused private address, an unusable proxy setting) and arguments that do not match the tool's schema are returned as a tool result with `isError: true`, whose text starts `Error executing tool fetch:` and says what went wrong, so the model can read it and decide what to do.
37+
- Calling a tool the server does not have is a JSON-RPC protocol error, `-32602` (`Unknown tool: <name>`), as the specification requires. So is getting a prompt it does not have (`Unknown prompt: <name>`), or the `fetch` prompt without its `url` (`URL is required`).
38+
- When the `fetch` prompt's fetch fails, the prompt still returns: its message holds the reason the fetch failed.
39+
40+
The server is built on the MCP Python SDK's high-level `MCPServer`: the tool and the prompt are decorated functions, and their type hints and field descriptions are the input schema and the prompt's arguments.
41+
3442
### Protocol versions
3543

3644
The server speaks both eras of the Model Context Protocol over stdio, with nothing to configure: a **2026-07-28** client (discovered with `server/discover`, no session) and a **2025-11-25** client (the `initialize` handshake). The client's first request decides which. Tools and prompts behave the same in both. Methods the 2026-07-28 specification removes, such as `ping`, are answered only on a 2025-11-25 connection.

‎src/fetch/pyproject.toml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ classifiers = [
1818
dependencies = [
1919
"httpx[socks]>=0.27",
2020
"markdownify>=0.13.1",
21-
"jsonschema>=4.20.0",
2221
"mcp>=2.2,<3",
2322
"protego>=0.6.2",
2423
"pydantic>=2.0.0",

0 commit comments

Comments
 (0)