MCP Template

Production-ready MCP (Model Context Protocol) server template in Python with registry integration, comprehensive configuration management, and extensibility patterns.

Features

Production-Ready: Enterprise-grade error handling, structured logging, and graceful shutdown
Registry Integration: Automatic server registration, heartbeats, and deregistration
Configuration Management: YAML-based config with environment variable overrides and Pydantic validation
Extensible Architecture: Easy-to-extend base classes for tools, resources, and prompts
Type Safety: Full type hints throughout the codebase
Developer Experience: Comprehensive CLI, extensive documentation, and example implementations
Testing: Unit and integration test examples with pytest

Quick Start

Installation

# Clone or copy this template
cd mcp-template

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Or using requirements.txt
pip install -r requirements-dev.txt

Initialize Configuration

# Initialize default configuration
mcp-template init

# This creates:
# - config/config.yaml (server configuration)
# - .env (environment variables)

Run the Server

# Run with default configuration
mcp-template run

# Run with custom config
mcp-template run --config path/to/config.yaml

# Run in debug mode
mcp-template run --debug

# Validate configuration
mcp-template validate

# Check health
mcp-template health

Project Structure

mcp-template/
├── src/mcp_template/
│   ├── core/                  # Core server components
│   │   ├── server.py          # Base MCP server implementation
│   │   ├── settings.py        # Pydantic settings models
│   │   ├── config_loader.py   # Configuration loader
│   │   └── logger.py          # Structured logging setup
│   ├── registry/              # Registry integration
│   │   ├── base.py            # Registry client interface
│   │   ├── http_client.py     # HTTP registry implementation
│   │   └── manager.py         # Registry lifecycle manager
│   ├── tools/                 # MCP tools
│   │   ├── calculator.py      # Example calculator tool
│   │   └── search.py          # Example search tool
│   ├── resources/             # MCP resources
│   │   ├── config.py          # Configuration resource
│   │   └── status.py          # Status resource
│   ├── prompts/               # MCP prompts
│   │   └── example.py         # Example prompt
│   ├── app.py                 # Main application
│   └── cli.py                 # Command-line interface
├── config/
│   └── config.yaml            # Server configuration
├── tests/
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
├── pyproject.toml             # Project metadata and dependencies
├── requirements.txt           # Production dependencies
├── requirements-dev.txt       # Development dependencies
├── Makefile                   # Development commands
└── README.md                  # This file

Configuration

Configuration File (config/config.yaml)

The main configuration file supports:

Server settings: Name, version, description, debug mode
Logging: Level, format (JSON/text), file output
Registry: URL, authentication, heartbeat settings, metadata
Tools/Resources/Prompts: Enable/disable specific components

Example:

server:
  name: "my-mcp-server"
  version: "0.1.0"
  description: "My custom MCP server"

logging:
  level: "INFO"
  format: "json"

registry:
  enabled: true
  url: "https://registry.example.com/api/v1"
  auth:
    type: "api_key"
    api_key: "${REGISTRY_API_KEY}"
  heartbeat:
    enabled: true
    interval: 60

tools:
  enabled:
    - "example_calculator"
    - "example_search"

Environment Variables

Override configuration using environment variables with double underscore as separator:

# Override server name
export SERVER__NAME="production-server"

# Override registry URL
export REGISTRY__URL="https://prod-registry.example.com"

# Set API key
export REGISTRY__AUTH__API_KEY="your-api-key"

# Override logging level
export LOGGING__LEVEL="DEBUG"

Environment Variables File (.env)

Create a .env file for local development:

# Registry
REGISTRY_API_KEY=your-api-key-here

# Server overrides
SERVER__DEBUG=false

# Logging
LOGGING__LEVEL=INFO

Adding Custom Components

Adding a New Tool

Create a new file in src/mcp_template/tools/:

# src/mcp_template/tools/my_tool.py
import mcp.types as types

async def my_tool_handler(arguments: dict) -> str:
    """Handle the tool call."""
    # Your implementation here
    return "Result"

MY_TOOL_SCHEMA = types.Tool(
    name="my_tool",
    description="Description of what the tool does",
    inputSchema={
        "type": "object",
        "properties": {
            "param1": {
                "type": "string",
                "description": "Parameter description"
            }
        },
        "required": ["param1"]
    }
)

from .tools.my_tool import my_tool_handler, MY_TOOL_SCHEMA

# In MCPTemplateApp._register_components():
self.server.register_tool(
    "my_tool",
    my_tool_handler,
    MY_TOOL_SCHEMA,
)

Enable it in config/config.yaml:

tools:
  enabled:
    - "my_tool"

Adding a New Resource

Similar pattern - create handler and schema, register in app.py, enable in config.

# src/mcp_template/resources/my_resource.py
import mcp.types as types

async def my_resource_handler(uri: str) -> str:
    """Handle resource read."""
    return "Resource data"

MY_RESOURCE_SCHEMA = types.Resource(
    uri="myresource://example",
    name="My Resource",
    description="Resource description",
    mimeType="application/json"
)

Adding a New Prompt

# src/mcp_template/prompts/my_prompt.py
import mcp.types as types

async def my_prompt_handler(arguments: dict) -> types.GetPromptResult:
    """Handle prompt request."""
    return types.GetPromptResult(
        description="Prompt description",
        messages=[
            types.PromptMessage(
                role="user",
                content=types.TextContent(
                    type="text",
                    text="Prompt text"
                )
            )
        ]
    )

MY_PROMPT_SCHEMA = types.Prompt(
    name="my_prompt",
    description="Prompt description",
    arguments=[
        types.PromptArgument(
            name="arg1",
            description="Argument description",
            required=True
        )
    ]
)

Registry Integration

The template includes a pluggable registry system for server discovery and management.

How It Works

Registration: On startup, server registers with the registry
Heartbeat: Periodic heartbeats maintain the registration
Deregistration: Graceful shutdown deregisters the server

Custom Registry Backend

Implement the RegistryClient interface for custom backends:

from mcp_template.registry.base import RegistryClient

class MyRegistryClient(RegistryClient):
    async def register(self, server_info: dict) -> dict:
        # Your implementation
        pass

    async def deregister(self, server_id: str) -> bool:
        # Your implementation
        pass

    # Implement other methods...

Then use it in your application:

from mcp_template.registry.manager import RegistryManager

registry_manager = RegistryManager(settings, client=MyRegistryClient())

Development

Setup Development Environment

# Install with development dependencies
pip install -e ".[dev]"

# Or using make
make install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run only unit tests
pytest tests/unit

# Run only integration tests
pytest tests/integration -m integration

# Using make
make test

Code Quality

# Format code
make format

# Lint code
make lint

# Type check
make typecheck

# Run all checks
make check

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run manually
pre-commit run --all-files

Deployment

Docker

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY src/ src/
COPY config/ config/

RUN pip install -e .

CMD ["mcp-template", "run"]

Build and run:

docker build -t mcp-template .
docker run -e REGISTRY_API_KEY=your-key mcp-template

Environment-Specific Configuration

Create different config files for each environment:

config/
├── config.yaml          # Default
├── config.dev.yaml      # Development
├── config.staging.yaml  # Staging
└── config.prod.yaml     # Production

Run with specific config:

mcp-template run --config config/config.prod.yaml

Monitoring and Observability

Structured Logging

All logs are structured (JSON format by default) for easy parsing:

{
  "timestamp": "2024-01-01T12:00:00.000Z",
  "level": "info",
  "event": "Server started",
  "server": "my-server",
  "version": "0.1.0"
}

Health Checks

# CLI health check
mcp-template health

# Programmatic health check
from mcp_template.app import create_app

app = create_app()
health = await app.server.health_check()

Troubleshooting

Common Issues

Configuration file not found

# Initialize configuration
mcp-template init

# Or specify path
mcp-template run --config path/to/config.yaml

Registry connection failed

# Check registry health
mcp-template health

# Disable registry temporarily
# In config.yaml:
registry:
  enabled: false

Import errors

# Reinstall in editable mode
pip install -e .

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Run code quality checks: make check
Submit a pull request

mcp-template