mcp-server-template

A starting point for MCP servers that are going in front of real users, not just a demo. Clone it, replace the three example tools with your product's operations, and you already have:

• Bearer-token auth on the HTTP transport (MCP_TOKENS="alice:token1,bob:token2"), constant-time compare, 401 + WWW-Authenticate on failure

• Per-client rate limits (sliding window per token, 429 + Retry-After) and a process-wide tool budget as defense in depth

• Host allow-list (the SDK's DNS-rebinding protection, configured instead of disabled)

• Structured call logging: one JSON line per request with method, tool, duration, outcome

• stdio and Streamable HTTP from the same code (mcp-template stdio / mcp-template http)

• Tests that run without a network (Starlette TestClient against the real transport), CI on Linux and macOS, a Dockerfile that runs as non-root

• Tool docstrings written for the model, and a swappable Backend class so tests never touch your real API

Built on the official Python SDK (mcp 2.x, MCPServer).

Quickstart

git clone https://github.com/JustFady/mcp-server-template my-server && cd my-server
uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest -q

# local, for Claude Desktop / Claude Code / Cursor
.venv/bin/mcp-template stdio

# network
MCP_TOKENS="alice:$(openssl rand -hex 24)" .venv/bin/mcp-template http --host 0.0.0.0 --port 8000 --rate 60
curl -s localhost:8000/healthz

Claude Code: claude mcp add my-server -- /path/to/.venv/bin/mcp-template stdio

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "my-server": { "command": "/path/to/.venv/bin/mcp-template", "args": ["stdio"] } } }

Remote clients connect to https://your-host/mcp with Authorization: Bearer <token>. Set the public hostname so the SDK's DNS-rebinding protection accepts it: --allowed-host mcp.example.com (repeatable) or MCP_ALLOWED_HOSTS=mcp.example.com,mcp.example.com:443. Unknown Host headers are rejected (421 from the SDK middleware; some servers surface it as 400).

Related MCP server: Python MCP Server Kit

Adapting it to your product

1. src/mcp_template/server.py: replace Backend with your API client and the example tools with 5–10 operations your users actually ask for. Keep return values small and structured; the model reads them every call.

2. Write each docstring as instructions to the model: what it does, when to use it, what it returns, what it must not be used for.

3. tests/: fake the backend; assert tool names, descriptions and error behavior.

4. Decide limits: --rate per client per minute; GlobalToolBudget per process.

5. Put it behind TLS (a reverse proxy or your platform's ingress). Rotate tokens by editing MCP_TOKENS and restarting.

Layout

src/mcp_template/
  server.py      tools + build_server()
  http.py        BearerAuth ASGI middleware, make_app()
  middleware.py  call_logger, GlobalToolBudget (MCP-level middleware)
  ratelimit.py   SlidingWindow
  __main__.py    CLI
tests/           ratelimit, server, http (real transport via TestClient)
Dockerfile, .github/workflows/ci.yml

Docker

docker build -t my-mcp .
docker run --rm -p 8000:8000 -e MCP_TOKENS="alice:changeme" my-mcp

Why not OAuth?

For a server you operate for a known set of clients, static bearer tokens over TLS are simpler to run and to audit. The SDK supports full OAuth (AuthSettings + a TokenVerifier) when you need third-party clients to self-register; this template leaves that door open rather than making you walk through it on day one.

License

MIT © Fady Youssef