python-mcp-server-generator

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. Keep that file. When the server uses secrets, append lines that exclude env files and other credential files.
• Keep and commit the lock file that uv writes. Review the resolved versions, and run later installs from that lock file.

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. Constrain every argument with types, Pydantic constraints, and allowlists. Use parameterized queries, and build each SQL statement or shell command from fixed text rather than from arguments. Expose narrow tools rather than generic execute or query tools. Use read-only or least-privilege database credentials and narrowly scoped API tokens. Require authorization for sensitive operations.
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. Return only the fields the tool needs. Treat text from external APIs or databases as untrusted data, keep it out of tool descriptions, and label or truncate free text from third parties.
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. Default to read-only tools and read-only credentials. Add a destructive tool only when the user explicitly asks for it. Annotations are hints to the host and enforce nothing, so a destructive tool must get user confirmation before it acts, for example through a Resolve parameter that returns Elicit, as the Gotchas describe, or through a confirm parameter that defaults to a dry run.
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. Keep every test and every assertion at full strength. Change a test only when the test itself is wrong, and explain the change to the user.
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"]
    }
  }
}

VS Code launches the command in this file. Review the file before you commit it or trust it in a cloned repository. The absolute path reveals a local directory.

For Claude Desktop, uv run mcp install server.py adds a persistent entry to the Claude Desktop settings outside the project folder, and it can replace an entry with the same name. Explain this to the user first. Run the command only after the user explicitly agrees, has checked for an entry with the same name, and has backed up the settings file.

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. The Inspector is optional, and the user starts it. It downloads and runs the Inspector package and a local proxy that can start processes. Use a recent patched release, keep it on localhost with its proxy authentication on, and stop it after use.

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.
• Give the server name as the first MCPServer argument. Give all other constructor arguments as keyword arguments. Their positional order changed in SDK v2.
• Set version. If you do not set it, the server reports an empty version.
• Give the transport options (transport, host, port, json_response, stateless_http, transport_security) to run(), not to MCPServer(...).
• The SDK v2 types use snake_case fields, for example read_only_hint, structured_content, and is_error.
• Raise ToolError for an error that the model must read. For other exceptions, the model gets only a generic error message. Write each ToolError message by hand. Keep raw exception text, stack traces, file paths, connection strings, credentials, and record data out of it, and log those details to stderr with secrets redacted.
• Do not raise MCPError for a tool failure. The client gets a protocol error, not a tool result with is_error. Many hosts do not show this error to the model.
• In a stdio server, stdout is the protocol channel. Do not call print(). Log to stderr with the logging module. Redact credentials, tokens, and user data in tool arguments and results from log messages.
• Read API keys and database credentials from environment variables. Keep them out of server.py, .vscode/mcp.json, tool results, and error messages, and keep any env file out of version control.
• Do not use ctx.elicit(). It fails on a 2026-07-28 connection. For user input during a tool call, annotate a parameter with Resolve(fn). Return Elicit(message, Model) from fn.
• Send list change notifications with await ctx.notify_tools_changed(). A 2026-07-28 connection drops ctx.session.send_tool_list_changed().
• For stdio and HTTP, the lifespan runs one time, when the server starts. Each in-memory Client(mcp) in a test runs the lifespan again. Read its object with ctx.request_context.lifespan_context.
• The 2026-07-28 revision deprecates these features (SEP-2577). Do not add them to a new server:
  • Sampling (ctx.session.create_message()): Call the LLM provider API directly. Read the provider API key from an environment variable or a secret store, and keep it out of the code and the client configuration.
  • Protocol logging (ctx.log(), ctx.info(), and similar methods): Use the standard logging module.
  • Roots (ctx.session.list_roots()): Get paths from tool parameters, resource URIs, or the server configuration.
• The 2026-07-28 revision has no SSE transport. Use Streamable HTTP.