Production-ready Python template for building MCP servers with FastMCP, FastAPI, OAuth, and OpenShift deployment.
Template MCP Server
A production-ready template for developing Model Context Protocol (MCP) servers using Python and FastMCP. This server provides a foundation for creating MCP-compliant servers with comprehensive examples of tools, structured logging, configuration management, and containerized deployment.
The template includes three example MCP tools: a multiply calculator, a code review prompt generator, and a Red Hat logo tool. It demonstrates best practices for MCP server development including proper error handling, health checks, multiple transport protocols (HTTP, SSE, streamable-HTTP), SSL support, and comprehensive development tooling.
Features
- FastMCP + FastAPI with multiple transport protocols (HTTP, SSE, streamable-HTTP)
- Three example tools: multiply calculator, code review prompt, Red Hat logo
- Pydantic configuration via environment variables
- Structured JSON logging with structlog
- SSL/TLS support for secure deployments
- Container-ready with Red Hat UBI base image
- OpenShift deployment manifests included
- Full CI/CD with GitHub Actions (tests, linting, security, releases)
- OAuth integration with PostgreSQL token storage
Quick Start
git clone https://github.com/redhat-data-and-ai/template-mcp-server
cd template-mcp-server
make install # creates venv, installs deps + pre-commit hooks
make local # starts server on localhost:5001Verify in another terminal:
curl http://localhost:5001/healthManual setup (without Make)
# Create venv and install
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit install
Configure and run
cp .env.example .env
template-mcp-server
Verify
curl http://localhost:5001/healthHow to Use This Template
Option 1: GitHub Template (Recommended)
- Click the "Use this template" button at the top of the repository page.
- Name your new repository (e.g.,
my-mcp-server). - Clone your new repository and follow the rename checklist below.
Option 2: Manual Clone
git clone https://github.com/redhat-data-and-ai/template-mcp-server.git my-mcp-server
cd my-mcp-server
rm -rf .git
git initRename Checklist
After creating your project, replace all references to template-mcp-server and templatemcpserver with your project name. The following files require updates:
| File / Directory | What to Change | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | templatemcpserver/ | Rename the package directory (e.g.,mymcpserver/) | | pyproject.toml | name, project.scripts entry, [project.urls], [tool.coverage.run] source | | Makefile | References in lint, local, and deployment targets | | Containerfile | COPY source path and CMD module path | | compose.yaml | container_name, service name, healthcheck URL | | deployment/openshift/ | App labels, image names, route hostnames in all manifests (deployment.yaml, route.yaml, kustomization.yaml, etc.) | | .github/workflows/ | Workflow names and paths | | README.md | Title, description, clone URL, and all badge URLs (tests, coverage, Codespaces) | | .env.example | Adjust defaults if your server uses a different port or protocol |
Verify Rename
Run this to catch any leftover references:
grep -rn "template.mcp" --include=".py" --include=".yaml" --include=".yml" --include=".toml" --include="*.md" .The output should be empty (or only match this README section itself).
Configuration
| Variable | Default | Description | | ----------------------------- | ------------- | -------------------------------------------------------------------- | | MCP_HOST | localhost | Server bind address | | MCP_PORT | 5001 | Server port (1024-65535) | | MCPTRANSPORTPROTOCOL | http | Transport protocol (http, sse, streamable-http) | | MCPSSLKEYFILE | None | SSL private key file path | | MCPSSLCERTFILE | None | SSL certificate file path | | ENABLEAUTH | False* | Enable OAuth authentication (see Auth Guide) | | USEEXTERNALBROWSER_AUTH | False | Browser-based OAuth for local dev | | PYTHONLOGLEVEL | INFO | Logging level |
\ ENABLE_AUTH defaults to False in .env.example but True in code. Always copy .env.example to .env to start with auth disabled.*
Documentation
| Guide | Description | | ------------------------------------- | ---------------------------------------------------------- | | Architecture | System diagrams, code structure, key components, MCP tools | | Development | Setup, running locally, testing, code quality | | Deployment | Podman, OpenShift, container configuration | | CI/CD | Workflows, pipeline features, running CI locally | | Contributing | Development workflow, commit conventions, PR process | | Security | Vulnerability reporting policy | | Changelog | Release history | | Authentication | OAuth setup, auth modes, troubleshooting | | Tutorial | Your First Tool in 5 Minutes | | Examples | FastMCP and LangGraph client examples |
Contributing
See CONTRIBUTING.md for detailed guidelines.
# Fork, clone, and set up
git clone https://github.com/<your-username>/template-mcp-server.git
cd template-mcp-server
make install
Create a branch, make changes, verify
git checkout -b feat/your-feature
make lint && make test && make pre-commit
Commit and open a PR
git commit -m "feat: your descriptive message"
git push origin feat/your-feature
