Python MCP SDK Best Practices

The Model Context Protocol (MCP) Python SDK (mcp on PyPI) provides the canonical Python implementation for building servers and clients that connect LLMs to external data and tools in a standardized way.

Installation

Use uv (recommended) or pip:

uv add "mcp[cli]"

or

pip install "mcp[cli]"

Requires Python ≥ 3.10. The [cli] extra adds the mcp CLI for development tooling.

Three Primitives

MCP servers expose three primitives to LLM clients:

Primitive Analogy Purpose

Resources GET endpoint Load data into LLM context (read-only)

Tools POST endpoint Execute actions, produce side effects

Prompts Template Reusable interaction patterns for LLMs

Choose the right primitive for each capability:

• Use Resources for data retrieval that has no side effects.

• Use Tools for operations that compute, write, or call external APIs.

• Use Prompts for structured instruction templates clients can invoke by name.

FastMCP — The High-Level API

FastMCP is the primary interface. It wraps the low-level protocol and handles connection management, message routing, and serialization automatically.

Server Initialization

from mcp.server.fastmcp import FastMCP

mcp = FastMCP( "MyServer", stateless_http=True, # recommended for production HTTP json_response=True, # recommended for scalability )

Always name servers descriptively — the name appears in client UIs and logs.

Defining Tools

Annotate function parameters and return types. FastMCP generates JSON Schema from type hints automatically.

from pydantic import BaseModel, Field

class WeatherData(BaseModel): temperature: float = Field(description="Temperature in Celsius") condition: str humidity: float

@mcp.tool() def get_weather(city: str, unit: str = "celsius") -> WeatherData: """Get current weather for a city.

Returns structured weather data validated against WeatherData schema.
"""
# Implementation calls a real weather API
return WeatherData(temperature=22.5, condition="sunny", humidity=45.0)

Key rules for tools:

• Write clear, descriptive docstrings — LLMs use them to decide when to call the tool.

• Use Pydantic BaseModel return types for structured output; the schema is exposed to clients.

• Use TypedDict or dataclass as lighter alternatives when full Pydantic validation is not needed.

• Prefer async def for I/O-bound tools to avoid blocking the event loop.

• Add ctx: Context parameter last when progress reporting or logging is needed.

Defining Resources

@mcp.resource("file://documents/{name}") def read_document(name: str) -> str: """Read a document by name from the document store.""" # Read from disk, DB, or cache return f"Content of {name}"

@mcp.resource("config://settings") def get_settings() -> str: """Return current application settings as JSON.""" return '{"theme": "dark", "debug": false}'

Resources must be idempotent and free of significant side effects. Use URI templates ({param} ) for dynamic resources.

Defining Prompts

from mcp.server.fastmcp.prompts import base

@mcp.prompt(title="Code Review") def review_code(code: str, language: str = "python") -> list[base.Message]: """Generate a structured code review prompt.""" return [ base.UserMessage(f"Please review this {language} code:"), base.UserMessage(f"{language}\n{code}\n"), base.AssistantMessage("I'll analyze the code for correctness, style, and potential issues."), ]

Context Object

Inject ctx: Context into any tool or resource function to access MCP capabilities. FastMCP injects it automatically — it does not appear in the tool's JSON Schema.

from mcp.server.fastmcp import Context, FastMCP from mcp.server.session import ServerSession

@mcp.tool() async def long_running_task( task_name: str, steps: int, ctx: Context[ServerSession, None], ) -> str: """Run a multi-step task with progress reporting.""" await ctx.info(f"Starting task: {task_name}")

for i in range(steps):
    await ctx.report_progress(
        progress=(i + 1) / steps,
        total=1.0,
        message=f"Step {i + 1} of {steps}",
    )

await ctx.info("Task complete")
return f"Completed {task_name}"

Context capabilities:

Method Purpose

await ctx.info(msg)

Send info log to client

await ctx.debug(msg)

Send debug log

await ctx.warning(msg)

Send warning log

await ctx.error(msg)

Send error log

await ctx.report_progress(progress, total, message)

Report numeric progress

await ctx.read_resource(uri)

Read another resource from within a tool

await ctx.elicit(message, schema)

Request structured input from the user

ctx.request_id

Unique ID for current request

ctx.fastmcp

Access server instance metadata

Lifespan — Managing Shared Resources

Use the lifespan pattern for database connections, HTTP clients, or any resource that must be initialized once and shared across requests.

from collections.abc import AsyncIterator from contextlib import asynccontextmanager from dataclasses import dataclass

import httpx from mcp.server.fastmcp import Context, FastMCP

@dataclass class AppState: http_client: httpx.AsyncClient

@asynccontextmanager async def lifespan(server: FastMCP) -> AsyncIterator[AppState]: async with httpx.AsyncClient() as client: yield AppState(http_client=client)

mcp = FastMCP("MyServer", lifespan=lifespan)

@mcp.tool() async def fetch_url(url: str, ctx: Context) -> str: """Fetch content from a URL using the shared HTTP client.""" state: AppState = ctx.request_context.lifespan_context response = await state.http_client.get(url) return response.text

Always type the lifespan context with a @dataclass or TypedDict — this provides IDE support and avoids attribute lookup errors at runtime.

Error Handling

Raise standard Python exceptions in tools — MCP transmits them as structured error responses.

@mcp.tool() def divide(a: float, b: float) -> float: """Divide a by b.""" if b == 0: raise ValueError("Division by zero is not allowed") return a / b

For tools that can return partial results, use CallToolResult directly:

from mcp.types import CallToolResult, TextContent

@mcp.tool() def safe_parse(data: str) -> CallToolResult: """Parse data, returning errors inline rather than raising.""" try: result = parse(data) return CallToolResult( content=[TextContent(type="text", text=str(result))] ) except ParseError as exc: return CallToolResult( content=[TextContent(type="text", text=f"Parse failed: {exc}")], isError=True, )

Use isError=True to signal tool-level failures that should not halt the LLM's reasoning.

Quick Reference

Start dev server with MCP Inspector

uv run mcp dev server.py

Install to Claude Desktop

uv run mcp install server.py --name "My Server"

Run with extra dependencies

uv run mcp dev server.py --with pandas --with numpy

Run production HTTP server (uvicorn)

uvicorn server:mcp.streamable_http_app --host 0.0.0.0 --port 8000

Pattern Recommendation

Transport (production) Streamable HTTP with stateless_http=True, json_response=True

Transport (local/stdio) stdio via mcp.run() or uv run mcp run server.py

I/O tools Use async def

Shared state Use lifespan context

Structured output Return Pydantic BaseModel subclass

Progress reporting Use ctx.report_progress()

Secrets/config Pass via environment variables, not hardcoded

Additional Resources

• references/server-patterns.md — Advanced patterns: structured output, elicitation, sampling, notifications, authentication, and mounting multiple servers.

• references/transports-and-deployment.md — Transport comparison (stdio vs SSE vs Streamable HTTP), CORS, ASGI mounting, and production deployment checklist.