MCP Server Starter

An opinionated, production-minded Python starter for exposing typed tools over the Model Context Protocol.

It deliberately uses the stable MCP Python SDK v1 line. SDK v2 is prerelease as of July 2026 and is not yet recommended for production.

What is included

• Streamable HTTP MCP endpoint at /mcp
• Typed tool inputs and structured outputs
• FastAPI health and readiness endpoints
• Request IDs and JSON access logs
• Environment-based configuration
• Stateless mode for horizontal scaling
• Unit, protocol, and HTTP tests
• Non-root Docker image
• Clear extension points for gateway authentication and telemetry

Quick start

Requirements: Python 3.11+ and uv.

uv sync --all-groups
uv run uvicorn mcp_server_starter.app:app --reload

The service exposes:

• MCP: http://localhost:8000/mcp
• Liveness: http://localhost:8000/health/live
• Readiness: http://localhost:8000/health/ready

Try it with the MCP Inspector:

npx @modelcontextprotocol/inspector

Use http://localhost:8000/mcp as the Streamable HTTP server URL.

Or run the included demo client in a second terminal:

uv run python scripts/demo_client.py

It discovers the available tools and calls echo over the Streamable HTTP endpoint.

Included tools

• echo: returns a validated message and request correlation ID
• service_status: returns service name, version, and health state

They are intentionally boring. Replace them with domain tools while keeping the surrounding operational shell.

Configuration

All settings use the MCP_STARTER_ prefix.

Variable	Default	Purpose
MCP_STARTER_ENVIRONMENT	development	Deployment environment name
MCP_STARTER_LOG_LEVEL	INFO	Python log level
MCP_STARTER_ALLOWED_ORIGINS	[]	JSON array of browser origins allowed by CORS

Example:

export MCP_STARTER_ENVIRONMENT=production
export MCP_STARTER_ALLOWED_ORIGINS='["https://your-mcp-client.example"]'

Architecture

MCP client
    |
identity-aware API gateway   <- authenticate, authorize, rate-limit
    |
FastAPI operational shell    <- health, request IDs, access logs
    |
MCP Streamable HTTP          <- protocol and typed schemas
    |
domain tools                 <- business authorization + services
    |
logs, traces, metrics, audit events

This starter does not pretend that a hard-coded API key is enterprise authentication. Terminate OAuth/OIDC at an identity-aware gateway, pass only trusted identity context to the application, and still enforce resource-level authorization inside each tool.

Development

uv run pytest
uv run ruff check .
uv run ruff format --check .

Build and run the container:

docker build -t mcp-server-starter .
docker run --rm -p 8000:8000 mcp-server-starter

Production checklist

• Put the service behind TLS and an identity-aware gateway.
• Restrict CORS to explicit origins; an empty list is the safe default.
• Add tool-level authorization—not only endpoint authentication.
• Emit audit events for every side-effecting tool.
• Add OpenTelemetry export for your chosen backend.
• Set timeouts, retries, and circuit breakers around downstream calls.
• Pin dependencies through uv.lock and scan the image in CI.
• Treat tool descriptions and schemas as part of your public API.

Author

JP Oliveira · LinkedIn