Sync the build-server and build-client tutorials with these examples #277

Problem

Each tutorial page links to this repo as "the complete code for this tutorial". The pages are in modelcontextprotocol/modelcontextprotocol, at docs/docs/<revision>/develop/build-client.mdx and build-server.mdx, in both the 2026-07-28 and draft copies. This issue tracks, from this side, what's still out of sync. The changes themselves are PRs to the spec repo.

Much of the drift has already been fixed or is in review there (checked 2026-11-01):

• Merged:
  • docs: update the Rust client tutorial to rmcp 3 modelcontextprotocol#3484 moved the Rust client tutorial to rmcp 3: no genai, serve_with_lifecycle, a capped tool loop.
  • docs: handle non-text and multiple tool-use blocks in the client tutorial modelcontextprotocol#3476 handles non-text content and multiple tool_use blocks.
  • docs: fix Java and Kotlin tutorial samples that fail as printed modelcontextprotocol#3481 fixed the Java and Kotlin samples.
  • docs: fix stale one-liners in the build tutorials modelcontextprotocol#3474 and docs: small fixes and released/draft sync modelcontextprotocol#3478 made small fixes and synced the draft copy.
• Open:
  • docs: run a full tool loop in the client tutorial modelcontextprotocol#3482 adds a full tool loop to the Python, TypeScript, Kotlin and Ruby client tabs, and raises max_tokens to 10000 in every tab, including C#. It would also resolve Bug in the official tutorial docs: Tool use example code lacks agentic loop, causing multi-turn calls to fail #233 here.
  • docs: update the Rust server tutorial to rmcp 3 modelcontextprotocol#3479 moves the Rust server tutorial from rmcp 0.3 to rmcp 3, with output schemas and structured content.

What's left

• Get docs: run a full tool loop in the client tutorial modelcontextprotocol#3482 and docs: update the Rust server tutorial to rmcp 3 modelcontextprotocol#3479 reviewed and merged.
• Explain stop_reason. No page mentions it, so a reply cut off by max_tokens or refused by the model looks like an empty answer. This should follow Add a system prompt and stop_reason handling to the clients #274, so the pages and the examples teach the same thing.
• Use the same model ID as the examples. Every tab in the client tutorial uses claude-opus-5, and every example here uses claude-sonnet-5. That isn't a bug, but pick one and say why.
• Add a Go tab or say there isn't one. The client tutorial has no Go tab, though mcp-client-go exists here and the smoke tests cover it. The server tutorial does cover Go.
• Cover structured content in the server tutorial's other tabs. Apart from the Rust tab in docs: update the Rust server tutorial to rmcp 3 modelcontextprotocol#3479, the page has no outputSchema, structuredContent or structured_content. Yet all five servers here declare output schemas and return structured content, and it's a headline feature of the revision this page is filed under. The array-rooted case is worth showing, because get_alerts uses it and 2025-11-25 clients can't handle it (see Stop breaking 2025-11-25 clients with get_alerts' array output schema #272).
• Cover tool annotations. The server tutorial has no annotations, readOnlyHint or openWorldHint. This should follow Add tool annotations to both tools in every server #271.
• Decide who owns the C#, Java and Kotlin tabs. This repo has no example to check them against.

Order of work

• Normalize the five weather servers renames the TypeScript tools to get_alerts / get_forecast. The server tutorial already uses underscores everywhere, so after the rename the page is correct without an edit.
• Add tool annotations to both tools in every server #271 and Clients: fix what goes into a tool_result (Python, TypeScript, Go, Ruby) #273 both change what the tutorials should show, so update the pages after they land.

Acceptance criteria

• Every code block in both pages compiles and runs against the current examples.
• No page pins an SDK version older than the one this repo pins.
• The server tutorial shows output schemas and structured content in every tab.