python-starter MCP server

MCP server Python starter

A production-ready Model Context Protocol server in Python, ready to customize with coding agents. It runs over stdio for local clients and Streamable HTTP for remote ones, with OAuth, sample tools that include calls to a backend API, tests through real MCP clients, and a release pipeline.

Features

• Current protocol: built on the official MCP Python SDK v2 and its MCPServer API, for the 2026-07-28 spec, while still serving older clients.
• Two transports: stdio for Claude Code, Claude Desktop, and Cursor, plus stateless Streamable HTTP that scales horizontally.
• Secure HTTP: OAuth per the MCP authorization spec, with per-tool scopes and 403 scope challenges, or static tokens. It won't start without an auth mode, and it blocks DNS rebinding.
• Typed tools: get_time, search_docs, and whoami use type hints and Pydantic models as their schemas, with annotations and readable errors, plus docs:// resources.
• Backend integration: list_notes and create_note call any REST API that meets a documented notes contract, with deadlines, validated responses, and errors the model can act on. They use a service account, or act as each user through token exchange. See Connect a backend API.
• Production ready: readiness and graceful drain, OpenTelemetry traces and metrics, and a deploy guide with proxy, TLS, and identity provider setup.
• Real tests: tools are tested through real MCP clients in process, over stdio, and over HTTP, on both protocol eras, plus the built wheel and the Docker image.
• Strict gates: Ruff, mypy in strict mode, and 90% coverage.
• Publishing: releases to PyPI, the MCP Registry, and GHCR, with digest-pinned base images, a vulnerability scan before push, an SBOM, and provenance. A test keeps server.json, pyproject.toml, and the image label in step.
• Agent-ready: AGENTS.md, skills, and checks that run on every commit.

Quick start

You need uv, which installs Python 3.15 for you, and Node for the MCP Inspector:

git clone https://github.com/opikdev/mcp-server-python-starter
cd mcp-server-python-starter
make sync
make inspect

The MCP Inspector opens in your browser. Connect, list the tools, and call get_time. To try the notes tools too, pass the UPSTREAM_* settings, as Connect a backend API shows.

To run it over HTTP in Docker instead:

docker compose up --build --wait mcp

The server is now at http://localhost:3000/mcp, with the dev token dev-token-change-me-0123. To connect Claude Code, Claude Desktop, Cursor, or VS Code, see Connect a client.

Start your own project

Create a renamed copy with pik. It downloads this starter's latest release, then sets your project name and GitHub owner:

pik new mcp-server-python-starter my-mcp-server

Or select Use this template on GitHub. That copy keeps the name mcp-server-python-starter and the owner opikdev, so follow pik.yaml by hand: swap the replace text, delete the exclude paths, and run the setup commands.

Usage

Task	Command
Try the tools in the MCP Inspector	make inspect
Serve over HTTP on your machine	cp .env.example .env, then make dev
Run lint, types, tests with coverage, and repo checks	make verify
Test the built wheel, the Docker image, and an example backend	make e2e
Fix formatting and lint you can fix automatically	make format

To work in a dev container, open the folder in one: .devcontainer/ has Python, uv, and jq, so make verify runs inside it. make e2e needs Docker on the host. Over HTTP, the server needs an auth mode. See Configure HTTP auth.

To add a tool, create a module in src/mcp_app/tools/ with a register_* function, call it from src/mcp_app/server.py, and test it in tests/integration/test_tools.py. Before you release, read Publish a release.

Project structure

Path	Purpose
src/mcp_app/cli.py	Entry point: stdio by default, or HTTP with --http
src/mcp_app/server.py	Builds the server with every tool and resource
src/mcp_app/tools/	One module per tool, or a small related set
src/mcp_app/resources/	docs:// resources
src/mcp_app/http.py, src/mcp_app/auth/	The HTTP app, health and readiness, token verifiers, and scope challenges
src/mcp_app/upstream/	Clients for backend APIs, and the credential each call uses
compose.auth.yaml, keycloak/	A local Keycloak for OAuth and token exchange
tests/	Unit, integration, and end-to-end tests
server.json	MCP Registry metadata
docs/	Architecture, guides, and decisions

Contributing

Read CONTRIBUTING.md before opening a pull request, and follow the code of conduct.

Security

Report vulnerabilities privately, as described in SECURITY.md.

License

Released under the MIT License.