Python MCP Server Generator

Create a Model Context Protocol (MCP) server in Python with the official MCP Python SDK v2. SDK v2 supports the MCP specification revision 2026-07-28. The same server also serves clients that use earlier revisions.

Workflow

Copy this checklist and track your progress:

• Step 1: Create the project.
• Step 2: Write the server.
• Step 3: Write the tests.
• Step 4: Run the tests until they pass.
• Step 5: Configure the client.

Step 1: Create the project

Run these commands:

uv init --app --no-package project-name
cd project-name
uv add "mcp[cli]>=2,<3"
uv add --dev pytest

Then delete main.py. The server goes in server.py.

• Without --no-package, uv makes a src/ package layout, and the tests cannot import server.py.
• uv init makes the .gitignore file. Do not write a different one.

Step 2: Write the server

Start from this template:

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("Demo", version="0.1.0")


@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide a by b."""
    if b == 0:
        raise ToolError("b must not be zero.")
    return a / b


if __name__ == "__main__":
    mcp.run()  # stdio is the default transport

Then change the template for the request of the user:

1. Replace divide with the tools that the user needs.
2. Give each tool full type hints and a docstring. The SDK makes the input schema from the type hints. The docstring becomes the tool description.
3. Return a Pydantic model or a TypedDict when the client needs machine-readable data. The SDK makes the output schema from the return type.
4. Use async def for I/O. The SDK runs a sync tool on a worker thread.
5. Mark a read-only tool with @mcp.tool(annotations=ToolAnnotations(read_only_hint=True)) (from mcp.types). Use destructive_hint=True for a destructive tool.
6. Add resources (@mcp.resource("users://{user_id}")) and prompts (@mcp.prompt()) only when the user asks for them.

Use stdio by default. Read references/streamable-http.md only when the user asks for a remote server or an HTTP server.

Step 3: Write the tests

Put test_server.py next to server.py. Write a test for each tool and for each ToolError:

import pytest

from mcp import Client

from server import mcp


@pytest.mark.anyio
async def test_divide():
    async with Client(mcp) as client:
        result = await client.call_tool("divide", {"a": 6, "b": 3})
        assert result.structured_content == {"result": 2.0}


@pytest.mark.anyio
async def test_divide_by_zero():
    async with Client(mcp) as client:
        result = await client.call_tool("divide", {"a": 1, "b": 0})
        assert result.is_error
        assert "must not be zero" in result.content[0].text

• The in-memory Client needs no subprocess and no port. It connects with the 2026-07-28 revision.
• The mcp package installs anyio, which supplies the anyio marker. Do not add pytest-asyncio.

Step 4: Run the tests until they pass

1. Run uv run pytest.
2. If a test fails, read the error. Fix the server or the test.
3. Run uv run pytest again.
4. Continue only when all tests pass.

Step 5: Configure the client

For VS Code, write .vscode/mcp.json:

{
  "servers": {
    "demo": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/project", "run", "server.py"]
    }
  }
}

For Claude Desktop, run uv run mcp install server.py.

Tell the user these commands:

• uv run server.py starts the stdio server. The server waits for a host on stdin and prints nothing.
• uv run mcp dev server.py opens the MCP Inspector. The Inspector needs Node.js.

Gotchas

SDK v2 and the 2026-07-28 revision changed many SDK v1 patterns. Do not copy SDK v1 examples.

• SDK v2 removed FastMCP and mcp.server.fastmcp. Import the server class with from mcp.server import MCPServer.
• Import Context, Image, Audio, Resolve, Elicit, ElicitationResult, AcceptedElicitation, Message, UserMessage, and AssistantMessage from mcp.server.mcpserver.

…