mcp-http-template by raihan0824 - MCP Server

MCP HTTP Template Server

A clean, professional template for building MCP (Model Context Protocol) servers using streamable HTTP transport. This template is based on the official simple-streamablehttp example from the MCP Python SDK.

Features

✅ Low-level MCP Server implementation - Uses the official MCP Python SDK's low-level server
✅ Streamable HTTP transport - Full support for HTTP-based MCP communication
✅ Resumability support - Built-in event store for connection resumption
✅ Example tools and resources - Ready-to-use examples you can extend
✅ Professional structure - Clean, maintainable code organization
✅ Development tools - Linting, formatting, and testing setup
✅ Easy configuration - Environment-based configuration management
✅ CORS support - Ready for browser-based clients

Quick Start

Prerequisites

Python 3.10 or higher
pip or uv for package management

Installation

Clone or download this template:

git clone https://github.com/raihan0824/mcp-http-template.git
cd mcp-http-template

Install dependencies:

# Using pip
pip install -r requirements.txt

# Or using uv (recommended)
uv sync

Run the server:
```
python -m mcp_server.main
```
The server will start on http://127.0.0.1:3000 by default.

Using Make (Optional)

This template includes a Makefile for common tasks:

# Install dependencies
make install

# Install development dependencies
make install-dev

# Run the server
make run

# Format code
make format

# Run linting
make lint

# Run type checking
make type-check

# Docker commands
make docker-build    # Build Docker image
make docker-run      # Run with docker-compose
make docker-dev      # Run development version
make docker-stop     # Stop containers
make docker-logs     # View logs

Docker Deployment

Quick Start with Docker

Build and run with Docker Compose:
```
docker-compose up -d
```

Or build and run manually:

docker build -t mcp-http-template .
docker run -p 3000:3000 mcp-http-template

Docker Features

✅ Non-root user: Runs as mcpuser (UID 1000) for security
✅ Multi-stage build: Optimized image size and security
✅ Health checks: Built-in container health monitoring
✅ Environment variables: Full configuration via env vars
✅ Security hardened: No new privileges, minimal attack surface

Docker Environment Variables

All configuration can be done via environment variables:

docker run -p 3000:3000 \
  -e MCP_SERVER_NAME="My Custom Server" \
  -e MCP_LOG_LEVEL="DEBUG" \
  -e MCP_PORT=3000 \
  mcp-http-template

Development with Docker

For development with live code reloading:

# Run development container with volume mounts
docker-compose --profile dev up -d mcp-server-dev

# View logs
docker-compose logs -f mcp-server-dev

Configuration

Command Line Options

python -m mcp_server.main --help

Options:
  --port INTEGER          Port to listen on for HTTP (default: 3000)
  --log-level TEXT        Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  --json-response         Enable JSON responses instead of SSE streams
  --help                  Show this message and exit.

Environment Variables

Copy env.example to .env and modify as needed:

cp env.example .env

Available environment variables:

MCP_SERVER_NAME - Server name (default: "MCP HTTP Template Server")
MCP_HOST - Host to bind to (default: "localhost")
MCP_PORT - Port to listen on (default: 8000)
MCP_LOG_LEVEL - Logging level (default: "INFO")
MCP_ENABLE_TOOLS - Enable tools (default: "true")
MCP_ENABLE_RESOURCES - Enable resources (default: "true")
MCP_ENABLE_PROMPTS - Enable prompts (default: "true")

Available Tools

The template includes several example tools:

1. `greet`

Greet someone by name.

{
  "name": "greet",
  "arguments": {
    "name": "Alice"
  }
}

2. `calculate`

Perform basic mathematical calculations.

{
  "name": "calculate",
  "arguments": {
    "operation": "add",
    "a": 5,
    "b": 3
  }
}

3. `get_server_info`

Get information about the server.

{
  "name": "get_server_info",
  "arguments": {}
}

4. `send_notification`

Send a stream of notifications (demonstrates streaming capabilities).

{
  "name": "send_notification",
  "arguments": {
    "interval": 1.0,
    "count": 3,
    "caller": "test-client"
  }
}

Available Resources

1. `server://status`

Get the current server status.

2. `server://config`

Get the current server configuration.

Testing the Server

Using curl

Test basic connectivity:

curl -X POST http://127.0.0.1:3000/mcp \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Call a tool:

curl -X POST http://127.0.0.1:3000/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "greet",
      "arguments": {"name": "World"}
    }
  }'

List resources:

curl -X POST http://127.0.0.1:3000/mcp \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc": "2.0", "id": 1, "method": "resources/list"}'

Using an MCP Client

This server is compatible with any MCP client that supports the streamable HTTP transport. The server endpoint is:

http://127.0.0.1:3000/mcp

Customizing the Template

Adding New Tools

Add your tool handler in mcp_server/main.py:

elif name == "your_tool_name":
    # Your tool logic here
    result = "Your result"
    return [types.TextContent(type="text", text=result)]

Add the tool definition to list_tools():

types.Tool(
    name="your_tool_name",
    description="Description of your tool",
    inputSchema={
        "type": "object",
        "required": ["param1"],
        "properties": {
            "param1": {
                "type": "string",
                "description": "Parameter description"
            }
        }
    }
)

Adding New Resources

Add the resource to list_resources():

types.Resource(
    uri=AnyUrl("your://resource"),
    name="Your Resource",
    description="Description of your resource",
    mimeType="text/plain"
)

Handle the resource in read_resource():

elif str(uri) == "your://resource":
    return "Your resource content"

Development

Code Formatting

This template uses Black and isort for code formatting:

# Format code
make format

# Check formatting
make lint

Type Checking

Type checking is done with mypy:

make type-check

Project Structure

mcp-http-template/
├── mcp_server/
│   ├── __init__.py          # Package initialization
│   ├── main.py              # Main server implementation
│   └── config.py            # Configuration management
├── tests/
│   └── __init__.py          # Tests package
├── requirements.txt         # Python dependencies
├── pyproject.toml          # Project configuration
├── Makefile                # Development commands
├── env.example             # Environment variables template
├── .gitignore              # Git ignore rules
└── README.md               # This file

Production Deployment

Important Notes

Event Store: The included InMemoryEventStore is for demonstration only. For production, implement a persistent event store (Redis, database, etc.).

Security: Update CORS settings in production:

starlette_app = CORSMiddleware(
    starlette_app,
    allow_origins=["https://yourdomain.com"],  # Specific origins
    allow_methods=["GET", "POST", "DELETE"],
    expose_headers=["Mcp-Session-Id"],
)

Logging: Configure appropriate logging levels and handlers for production.
Error Handling: Add comprehensive error handling for your specific use cases.

License

This template is provided under the MIT License. See the LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For questions about MCP:

For issues with this template:

Open an issue in this repository
Check the existing issues for similar problems

Happy coding! 🚀