Python MCP Server Kit

A backend-only starter for secure, typed, and testable Model Context Protocol servers. It targets the MCP 2026-07-28 protocol through the official Python SDK v2 and uses stateless Streamable HTTP for deployment.

Features

• Typed tools with structured Pydantic output

• Generic calculator and deterministic catalog examples

• MCP tools, resources, and prompts

• Bearer-token boundary and per-tool scopes

• Request-size, host, and in-process rate limits

• Correlation IDs and structured request logs

• Public health and readiness probes

• Unit and HTTP integration tests

• Production-style non-root Docker image

• CI for lint, formatting, typing, tests, image build, secrets, and workflows

Related MCP server: MCP TypeScript SDK

Architecture

HTTP request
  -> SecurityMiddleware (host, size, auth, rate limit, request ID)
  -> MCP Streamable HTTP transport
  -> typed tool/resource/prompt
  -> scope check
  -> deterministic domain function

Protocol registration lives in src/mcp_server_kit/server.py; reusable domain logic stays in separate modules. TokenStore is intentionally a replaceable deployment boundary, not a full authorization server.

Quick start

Python 3.11+ is required.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\scripts\dev.ps1

The MCP endpoint is http://127.0.0.1:8000/mcp. Health probes are available at /health and /ready. The local-only demo tokens are:

• demo-reader — catalog:read

• demo-operator — catalog:read, calculator:use

Run MCP Inspector with npx -y @modelcontextprotocol/inspector and set an Authorization: Bearer demo-operator header. A credential-free client shape is available in examples/client.json; inject MCP_CLIENT_TOKEN locally.

Commands

.\scripts\dev.ps1    # development server with reload
.\scripts\check.ps1  # lint, format check, mypy, and tests
docker compose up --build

Configuration

Never commit .env. See security and deployment before an internet-facing deployment and adding tools when extending the registry.

Deployment notes

Set MCP_ENVIRONMENT=production, MCP_AUTH_MODE=bearer, a secret-managed MCP_BEARER_TOKENS value, and the exact public host allowlist. Terminate TLS at a trusted reverse proxy. Replace the starter token store with your OAuth 2.1 resource-server verifier when user delegation or token lifecycle management is required.

License

MIT