docs: stop presenting the in-memory client as the way to connect (#3443)

docs_src/apps/tutorial001.py

@@ -1,6 +1,4 @@
-from mcp import Client
-from mcp.client import advertise
-from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID, Apps, client_supports_apps
+from mcp.server.apps import Apps, client_supports_apps
 from mcp.server.mcpserver import MCPServer
 from mcp.server.mcpserver.context import Context
 
@@ -30,10 +28,3 @@ def get_time(ctx: Context) -> str:
 apps.add_html_resource("ui://clock/app.html", CLOCK_HTML, title="Clock")
 
 mcp = MCPServer("clock", extensions=[apps])
-
-
-async def main() -> None:
-    async with Client(mcp, extensions=[advertise(EXTENSION_ID, {"mimeTypes": [APP_MIME_TYPE]})]) as client:
-        result = await client.call_tool("get_time", {})
-        print(result.content)
-        # [TextContent(text='2026-06-26T12:00:00Z')]

docs_src/apps/tutorial001_client.py

@@ -0,0 +1,20 @@
+import anyio
+
+from mcp import Client
+from mcp.client import advertise
+from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID
+from mcp.types import TextContent
+
+APPS_SUPPORT = advertise(EXTENSION_ID, {"mimeTypes": [APP_MIME_TYPE]})
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp", extensions=[APPS_SUPPORT]) as client:
+        result = await client.call_tool("get_time", {})
+        for block in result.content:
+            if isinstance(block, TextContent):
+                print(block.text)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/caching/tutorial002.py

@@ -7,6 +7,7 @@ TOOLS = [Tool(name="forecast", input_schema={"type": "object"})]
 
 
 async def list_tools(ctx: ServerRequestContext[Any], params: PaginatedRequestParams | None) -> ListToolsResult:
+    print("tools/list served")
     return ListToolsResult(tools=TOOLS, ttl_ms=1_000)
 
 
@@ -15,3 +16,4 @@ server = Server(
     on_list_tools=list_tools,
     cache_hints={"tools/list": CacheHint(ttl_ms=60_000, scope="public")},
 )
+app = server.streamable_http_app()

docs_src/caching/tutorial003.py

@@ -1,39 +1,34 @@
 from dataclasses import dataclass
-from typing import Any
+
+import anyio
 
 from mcp import Client
 from mcp.client import CacheConfig
-from mcp.server import CacheHint, Server, ServerRequestContext
-from mcp.types import ListToolsResult, PaginatedRequestParams, Tool
+from mcp.types import ListToolsResult
 
 
 @dataclass
-class DemoState:
-    fetches: int = 0
-    now: float = 1_000_000.0
+class Clock:
+    now: float = 0.0
 
 
-state = DemoState()
+clock = Clock()  # advanced by hand below, so the TTL runs out without sleeping
 
 
-async def list_tools(ctx: ServerRequestContext[Any], params: PaginatedRequestParams | None) -> ListToolsResult:
-    state.fetches += 1
-    return ListToolsResult(tools=[Tool(name="forecast", input_schema={"type": "object"})])
-
-
-server = Server(
-    "Weather",
-    on_list_tools=list_tools,
-    cache_hints={"tools/list": CacheHint(ttl_ms=60_000, scope="public")},
-)
+async def run(client: Client) -> ListToolsResult:
+    tools = await client.list_tools()  # fetch 1
+    await client.list_tools()  # still fresh: served from the cache
+    clock.now += 2
+    await client.list_tools()  # past the one-second TTL: fetch 2
+    await client.list_tools(cache_mode="refresh")  # skip the cache read: fetch 3
+    return tools
 
 
 async def main() -> None:
-    start = state.fetches
-    async with Client(server, cache=CacheConfig(clock=lambda: state.now)) as client:
-        await client.list_tools()  # fetch 1
-        await client.list_tools()  # fresh for 60s: served from the cache
-        state.now += 60.0
-        await client.list_tools()  # the TTL ran out: fetch 2
-        await client.list_tools(cache_mode="refresh")  # skip the cache read: fetch 3
-        print(f"4 calls, {state.fetches - start} fetches")
+    async with Client("http://localhost:8000/mcp", cache=CacheConfig(clock=lambda: clock.now)) as client:
+        tools = await run(client)
+        print(tools.ttl_ms, tools.cache_scope)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial001.py

@@ -1,18 +1,56 @@
-from mcp import Client
+from pydantic import BaseModel
+
 from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import Completion, CompletionArgument, CompletionContext, PromptReference, ResourceTemplateReference
 
 mcp = MCPServer("Bookshop", instructions="Search the catalog before recommending a book.")
 
+GENRES = ["fiction", "non-fiction", "poetry"]
+
+
+class Book(BaseModel):
+    title: str
+    author: str
+    year: int
+
+
+@mcp.tool(title="Search the catalog")
+def search_books(query: str, limit: int = 10) -> str:
+    """Search the catalog by title or author."""
+    return f"Found 3 books matching {query!r} (showing up to {limit})."
+
 
 @mcp.tool()
-def search_books(query: str) -> str:
-    """Search the catalog by title or author."""
-    return f"Found 3 books matching {query!r}."
+def lookup_book(title: str) -> Book:
+    """Look up a book by its exact title."""
+    if title != "Dune":
+        raise ToolError(f"No book titled {title!r} in the catalog.")
+    return Book(title="Dune", author="Frank Herbert", year=1965)
 
 
-async def main() -> None:
-    async with Client(mcp) as client:
-        print(client.server_info)
-        print(client.server_capabilities)
-        print(client.protocol_version)
-        print(client.instructions)
+@mcp.resource("catalog://genres")
+def genres() -> list[str]:
+    """The genres the catalog is organised by."""
+    return GENRES
+
+
+@mcp.resource("catalog://genres/{genre}")
+def books_in_genre(genre: str) -> str:
+    """Every title we stock in one genre."""
+    return f"3 books filed under {genre}."
+
+
+@mcp.prompt(title="Recommend a book")
+def recommend(genre: str) -> str:
+    """Ask for a recommendation in a genre."""
+    return f"Recommend one {genre} book from the catalog and say why."
+
+
+@mcp.completion()
+async def complete_genre(
+    ref: PromptReference | ResourceTemplateReference,
+    argument: CompletionArgument,
+    context: CompletionContext | None,
+) -> Completion | None:
+    return Completion(values=[genre for genre in GENRES if genre.startswith(argument.value)])

docs_src/client/tutorial001_client.py

@@ -0,0 +1,15 @@
+import anyio
+
+from mcp import Client
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        print(client.server_info)
+        print(client.server_capabilities)
+        print(client.protocol_version)
+        print(client.instructions)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial002.py

@@ -1,20 +1,17 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
-
-mcp = MCPServer("Bookshop")
-
-
-@mcp.tool(title="Search the catalog")
-def search_books(query: str, limit: int = 10) -> str:
-    """Search the catalog by title or author."""
-    return f"Found 3 books matching {query!r} (showing up to {limit})."
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         result = await client.list_tools()
         for tool in result.tools:
             print(tool.name)
             print(tool.title)
             print(tool.description)
             print(tool.input_schema)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial003.py

@@ -1,29 +1,11 @@
-from pydantic import BaseModel
+import anyio
 
 from mcp import Client
-from mcp.server import MCPServer
-from mcp.server.mcpserver.exceptions import ToolError
 from mcp.types import TextContent
 
-mcp = MCPServer("Bookshop")
-
-
-class Book(BaseModel):
-    title: str
-    author: str
-    year: int
-
-
-@mcp.tool()
-def lookup_book(title: str) -> Book:
-    """Look up a book by its exact title."""
-    if title != "Dune":
-        raise ToolError(f"No book titled {title!r} in the catalog.")
-    return Book(title="Dune", author="Frank Herbert", year=1965)
-
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         result = await client.call_tool("lookup_book", {"title": "Dune"})
 
         for block in result.content:
@@ -32,3 +14,7 @@ async def main() -> None:
 
         print(result.structured_content)
         print(result.is_error)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial004.py

@@ -1,24 +1,11 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
 from mcp.types import TextResourceContents
 
-mcp = MCPServer("Bookshop")
-
-
-@mcp.resource("catalog://genres")
-def genres() -> list[str]:
-    """The genres the catalog is organised by."""
-    return ["fiction", "non-fiction", "poetry"]
-
-
-@mcp.resource("catalog://genres/{genre}")
-def books_in_genre(genre: str) -> str:
-    """Every title we stock in one genre."""
-    return f"3 books filed under {genre}."
-
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         listed = await client.list_resources()
         print([resource.uri for resource in listed.resources])
 
@@ -29,3 +16,7 @@ async def main() -> None:
         for contents in result.contents:
             if isinstance(contents, TextResourceContents):
                 print(contents.text)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial005.py

@@ -1,20 +1,17 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
-
-mcp = MCPServer("Bookshop")
-
-
-@mcp.prompt(title="Recommend a book")
-def recommend(genre: str) -> str:
-    """Ask for a recommendation in a genre."""
-    return f"Recommend one {genre} book from the catalog and say why."
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         listed = await client.list_prompts()
         print(listed.prompts)
 
         result = await client.get_prompt("recommend", {"genre": "poetry"})
         for message in result.messages:
             print(message.role, message.content)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial006.py

@@ -1,31 +1,17 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
-from mcp.types import Completion, CompletionArgument, CompletionContext, PromptReference, ResourceTemplateReference
-
-mcp = MCPServer("Bookshop")
-
-GENRES = ["fiction", "non-fiction", "poetry"]
-
-
-@mcp.prompt()
-def recommend(genre: str) -> str:
-    """Ask for a recommendation in a genre."""
-    return f"Recommend one {genre} book from the catalog and say why."
-
-
-@mcp.completion()
-async def complete_genre(
-    ref: PromptReference | ResourceTemplateReference,
-    argument: CompletionArgument,
-    context: CompletionContext | None,
-) -> Completion | None:
-    return Completion(values=[genre for genre in GENRES if genre.startswith(argument.value)])
+from mcp.types import PromptReference
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         result = await client.complete(
             ref=PromptReference(type="ref/prompt", name="recommend"),
             argument={"name": "genre", "value": "p"},
         )
         print(result.completion.values)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial007.py

@@ -1,30 +1,25 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
 from mcp.types import Tool
 
-mcp = MCPServer("Bookshop")
 
-
-@mcp.tool()
-def search_books(query: str) -> str:
-    """Search the catalog by title or author."""
-    return f"Found 3 books matching {query!r}."
-
-
-@mcp.tool()
-def reserve_book(title: str) -> str:
-    """Put a book on hold."""
-    return f"Reserved {title!r}."
+async def list_all_tools(client: Client) -> list[Tool]:
+    tools: list[Tool] = []
+    cursor: str | None = None
+    while True:
+        page = await client.list_tools(cursor=cursor)
+        tools.extend(page.tools)
+        if page.next_cursor is None:
+            return tools
+        cursor = page.next_cursor
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
-        tools: list[Tool] = []
-        cursor: str | None = None
-        while True:
-            page = await client.list_tools(cursor=cursor)
-            tools.extend(page.tools)
-            if page.next_cursor is None:
-                break
-            cursor = page.next_cursor
+    async with Client("http://localhost:8000/mcp") as client:
+        tools = await list_all_tools(client)
         print([tool.name for tool in tools])
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/extensions/tutorial003.py

@@ -1,7 +1,6 @@
 from collections.abc import Sequence
 from typing import Any
 
-from mcp import Client
 from mcp.server.extension import Extension, ToolBinding
 from mcp.server.mcpserver import MCPServer
 
@@ -24,12 +23,3 @@ class Stamps(Extension):
 
 
 mcp = MCPServer("post-office", extensions=[Stamps()])
-
-
-async def main() -> None:
-    async with Client(mcp) as client:
-        print(client.server_capabilities.extensions)
-        # {'com.example/stamps': {'sealed': True}}
-        result = await client.call_tool("stamp", {"text": "hello"})
-        print(result.content)
-        # [TextContent(text='[stamped] hello')]

docs_src/extensions/tutorial003_client.py

@@ -0,0 +1,16 @@
+import anyio
+
+from mcp import Client
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        print(client.server_capabilities.extensions)
+        # {'com.example/stamps': {'sealed': True}}
+        result = await client.call_tool("stamp", {"text": "hello"})
+        print(result.content)
+        # [TextContent(type='text', text='[stamped] hello', annotations=None, meta=None)]
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/extensions/tutorial004.py

@@ -1,11 +1,9 @@
 from collections.abc import Sequence
-from typing import Any, Literal
+from typing import Any
 
 from pydantic import Field
 
 import mcp.types as types
-from mcp import Client
-from mcp.client import advertise
 from mcp.server.context import ServerRequestContext
 from mcp.server.extension import Extension, MethodBinding
 from mcp.server.mcpserver import MCPServer, require_client_extension
@@ -22,11 +20,6 @@ class SearchResult(types.Result):
     items: list[str]
 
 
-class SearchRequest(types.Request[SearchParams, Literal["com.example/search"]]):
-    method: Literal["com.example/search"] = "com.example/search"
-    params: SearchParams
-
-
 async def search(ctx: ServerRequestContext[Any, Any], params: SearchParams) -> SearchResult:
     require_client_extension(ctx, EXTENSION_ID)
     return SearchResult(items=[f"{params.query}-{n}" for n in range(params.limit)])
@@ -49,11 +42,3 @@ class Search(Extension):
 
 
 mcp = MCPServer("catalog", extensions=[Search()])
-
-
-async def main() -> None:
-    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
-        request = SearchRequest(params=SearchParams(query="mcp", limit=3))
-        result = await client.session.send_request(request, SearchResult)
-        print(result.items)
-        # ['mcp-0', 'mcp-1', 'mcp-2']

docs_src/extensions/tutorial004_client.py

@@ -0,0 +1,35 @@
+from typing import Literal
+
+import anyio
+
+import mcp.types as types
+from mcp import Client
+from mcp.client import advertise
+
+EXTENSION_ID = "com.example/search"
+
+
+class SearchParams(types.RequestParams):
+    query: str
+    limit: int = 10
+
+
+class SearchResult(types.Result):
+    items: list[str]
+
+
+class SearchRequest(types.Request[SearchParams, Literal["com.example/search"]]):
+    method: Literal["com.example/search"] = "com.example/search"
+    params: SearchParams
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp", extensions=[advertise(EXTENSION_ID)]) as client:
+        request = SearchRequest(params=SearchParams(query="mcp", limit=3))
+        result = await client.session.send_request(request, SearchResult)
+        print(result.items)
+        # ['mcp-0', 'mcp-1', 'mcp-2']
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/extensions/tutorial006.py

@@ -1,9 +1,6 @@
-from collections.abc import Sequence
-from typing import Any, Literal
+from typing import Any
 
 import mcp.types as types
-from mcp import Client
-from mcp.client import ClaimContext, ClientExtension, ResultClaim
 from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
 from mcp.server.extension import Extension
 from mcp.server.mcpserver import MCPServer, require_client_extension
@@ -11,13 +8,6 @@ from mcp.server.mcpserver import MCPServer, require_client_extension
 EXTENSION_ID = "com.example/receipts"
 
 
-class ReceiptResult(types.Result):
-    """The claimed result shape; `result_type` pins the wire tag."""
-
-    result_type: Literal["receipt"] = "receipt"
-    receipt_token: str
-
-
 class ReceiptIssuer(Extension):
     """Server half: answers `buy` with a receipt instead of a final result."""
 
@@ -35,18 +25,6 @@ class ReceiptIssuer(Extension):
         return {"resultType": "receipt", "receiptToken": "r-117"}
 
 
-class Receipts(ClientExtension):
-    """Client half: claims the `receipt` shape and supplies the code that finishes it."""
-
-    identifier = EXTENSION_ID
-
-    def claims(self) -> Sequence[ResultClaim[Any]]:
-        return [ResultClaim(result_type="receipt", model=ReceiptResult, resolve=self._redeem)]
-
-    async def _redeem(self, claimed: ReceiptResult, ctx: ClaimContext) -> types.CallToolResult:
-        return await ctx.session.call_tool("redeem", {"token": claimed.receipt_token})
-
-
 mcp = MCPServer("shop", extensions=[ReceiptIssuer()])
 
 
@@ -60,10 +38,3 @@ def buy(item: str) -> types.CallToolResult:
 def redeem(token: str) -> str:
     """Exchange a receipt token for the goods."""
     return f"goods for {token}"
-
-
-async def main() -> None:
-    async with Client(mcp, extensions=[Receipts()]) as client:
-        result = await client.call_tool("buy", {"item": "lamp"})
-        print(result.content)
-        # [TextContent(text='goods for r-117')]

docs_src/extensions/tutorial006_client.py

@@ -0,0 +1,40 @@
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import anyio
+
+import mcp.types as types
+from mcp import Client
+from mcp.client import ClaimContext, ClientExtension, ResultClaim
+
+EXTENSION_ID = "com.example/receipts"
+
+
+class ReceiptResult(types.Result):
+    """The claimed result shape; `result_type` pins the wire tag."""
+
+    result_type: Literal["receipt"] = "receipt"
+    receipt_token: str
+
+
+class Receipts(ClientExtension):
+    """Client half: claims the `receipt` shape and supplies the code that finishes it."""
+
+    identifier = EXTENSION_ID
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        return [ResultClaim(result_type="receipt", model=ReceiptResult, resolve=self._redeem)]
+
+    async def _redeem(self, claimed: ReceiptResult, ctx: ClaimContext) -> types.CallToolResult:
+        return await ctx.session.call_tool("redeem", {"token": claimed.receipt_token})
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp", extensions=[Receipts()]) as client:
+        result = await client.call_tool("buy", {"item": "lamp"})
+        print(result.content)
+        # [TextContent(type='text', text='goods for r-117', annotations=None, meta=None)]
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/extensions/tutorial007.py

@@ -1,9 +1,7 @@
 from collections.abc import Sequence
-from typing import Any, Literal
+from typing import Any
 
 import mcp.types as types
-from mcp import Client
-from mcp.client import advertise
 from mcp.server.context import ServerRequestContext
 from mcp.server.extension import Extension, MethodBinding
 from mcp.server.mcpserver import MCPServer
@@ -19,12 +17,6 @@ class JobStatus(types.Result):
     status: str
 
 
-class JobStatusRequest(types.Request[JobParams, Literal["com.example/jobs.status"]]):
-    method: Literal["com.example/jobs.status"] = "com.example/jobs.status"
-    params: JobParams
-    name_param = "jobId"  # params["jobId"] rides the Mcp-Name header
-
-
 async def job_status(ctx: ServerRequestContext[Any, Any], params: JobParams) -> JobStatus:
     return JobStatus(status=f"{params.job_id} is running")
 
@@ -39,11 +31,3 @@ class Jobs(Extension):
 
 
 mcp = MCPServer("worker", extensions=[Jobs()])
-
-
-async def main() -> None:
-    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
-        request = JobStatusRequest(params=JobParams(job_id="job-7"))
-        result = await client.session.send_request(request, JobStatus)
-        print(result.status)
-        # job-7 is running

docs_src/extensions/tutorial007_client.py

@@ -0,0 +1,35 @@
+from typing import Literal
+
+import anyio
+
+import mcp.types as types
+from mcp import Client
+from mcp.client import advertise
+
+EXTENSION_ID = "com.example/jobs"
+
+
+class JobParams(types.RequestParams):
+    job_id: str
+
+
+class JobStatus(types.Result):
+    status: str
+
+
+class JobStatusRequest(types.Request[JobParams, Literal["com.example/jobs.status"]]):
+    method: Literal["com.example/jobs.status"] = "com.example/jobs.status"
+    params: JobParams
+    name_param = "jobId"  # params["jobId"] rides the Mcp-Name header
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp", extensions=[advertise(EXTENSION_ID)]) as client:
+        request = JobStatusRequest(params=JobParams(job_id="job-7"))
+        result = await client.session.send_request(request, JobStatus)
+        print(result.status)
+        # job-7 is running
+
+
+if __name__ == "__main__":
+    anyio.run(main)