GeezerVison

Client(server_object) connects in-process. That is how the SDK's own tests run and it is a fine test harness, but a lot of the documentation led with it: the client page's first example, the first section of the transports page, most "what Client accepts" lists, and most feature pages' client snippets. A reader came away thinking that importing the server object is how you write a client, with a URL as the variation.

This makes the docs show clients the way people write them: a server.py you serve, and a client.py that connects to http://localhost:8000/mcp (or a StdioServerParameters). In-memory stays where it belongs: the Testing page, "in tests" asides, and the transports page's "In memory" section.

Motivation and Context

Follows #3315 (README) and #3321 (Client(StdioServerParameters)), which came out of #3313. With those in, a real connection is one line either way, so the docs no longer need the in-memory form to keep examples short.

What changed:

• Client examples are real clients. On every page that had in-process client snippets, the server is shown once as server.py with the command that serves it (uv run mcp run server.py --transport streamable-http, or uvicorn server:app --port 8000 for a low-level Server), and each client snippet is its own client.py connecting by URL. That covers the client page (one Bookshop server.py, six clients), protocol versions (four clients against that same server), progress, extensions and MCP Apps (server/client pairs), pagination and caching (uvicorn-served low-level servers; the caching handler prints each real fetch so "four calls, three fetches" is visible across the process boundary), serving legacy clients (both eras from one client program), the low-level Server Try-it, and the inline fragments on the troubleshooting page. Where a client has logic worth testing (the pagination loop, the caching demo) it is a function that tests/docs_src drives in-process against the server module, the pattern the subscriptions page already used.
• Ordering. docs/client/transports.md leads with Streamable HTTP and stdio and moves "In memory" below them, scoped to tests and embedding. Enumerations that listed the server object first now put it last with "in tests" (whats-new.md, session-groups.md, multi-round-trip.md, callbacks.md, asgi.md, authorization.md, oauth-clients.md, four story READMEs). The Client docstring example is a URL client.
• Stale statements fixed along the way: callbacks.md "the first argument to Client(...) is a transport object", testing.md's "In-process by default" heading (now "Era-neutral by default") and intro, first-steps.md's description of what Client is.

Deliberately untouched: docs/migration.md, the translations under i18n/ (they regenerate; several now include docs_src files whose role changed and will show as outdated until then), and the examples/stories/README.md status table.

How Has This Been Tested?

• tests/docs_src retargeted rather than reduced: each page's claims are asserted in-process against its server module, and the factored client functions (list_all_tools, list_all_resources, the caching demo) are driven the same way. ./scripts/test passes at 100% coverage, scripts/docs/build.sh (strict) passes.
• Ran every new server/client pair by hand the way the pages say to: served each server.py with its stated command and ran each client.py against it (the client page's seven, protocol-versions' four, pagination, caching, legacy-clients, apps, four extensions pairs, progress, low-level). All exit cleanly and the pages' output blocks are the observed output; the caching server logs exactly three fetches for the client's four calls, and the legacy-clients client reserves in both eras over HTTP.

Breaking Changes

None. Documentation and examples only; the one src/ change is the Client docstring example.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Two commits: the first reorders and reframes, the second replaces the in-process example code (an earlier draft of this PR had added a sentence per page explaining the in-process snippets instead of changing them; that is gone). New docs_src files: client/tutorial001_client.py, apps/tutorial001_client.py, extensions/tutorial00{3,4,6,7}_client.py, legacy_clients/tutorial001_client.py.

_{AI Disclaimer}