Template MCP Server
Its a template that can be extended to write MCP servers following Enterprise best practices around Security and Deployment on Kubernetes
Installation
npx template-mcp-serverAsk AI about Template MCP Server
Powered by Claude · Grounded in docs
I know everything about Template MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:5001
Verify in another terminal:
curl http://localhost:5001/health
Manual 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/health
How 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 init
Rename Checklist
After creating your project, replace all references to template-mcp-server and template_mcp_server with your project name. The following files require updates:
| File / Directory | What to Change |
|---|---|
template_mcp_server/ | Rename the package directory (e.g.,my_mcp_server/) |
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) |
MCP_TRANSPORT_PROTOCOL | http | Transport protocol (http, sse, streamable-http) |
MCP_SSL_KEYFILE | None | SSL private key file path |
MCP_SSL_CERTFILE | None | SSL certificate file path |
ENABLE_AUTH | False* | Enable OAuth authentication (see Auth Guide) |
USE_EXTERNAL_BROWSER_AUTH | False | Browser-based OAuth for local dev |
PYTHON_LOG_LEVEL | 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