Container MCP Server

A Model Context Protocol (MCP) server designed for containerized deployment with HTTP transport. This server provides simple, dependency-free tools and prompts that can be used by MCP clients via streamable HTTP transport.

Features

HTTP Transport: Uses streamable HTTP transport for remote MCP server deployment
Container Ready: Optimized for Docker/Kubernetes deployment with health checks
Simple Tools: Weather data, mathematical calculations, and context-aware operations
Prompts: Reusable templates for weather reports and calculations
No External Dependencies: Mock data for easy testing and demonstration

Tools

1. get_weather

Get mock weather information for a city.

Parameters:

city (string, optional): City name (default: "San Francisco")

Returns: Weather data including temperature, condition, and humidity

2. sum_numbers

Add two numbers together.

Parameters:

a (float): First number
b (float): Second number

Returns: The sum of the two numbers

3. context_info

Demonstrate MCP context capabilities including logging, progress reporting, and metadata access.

Parameters:

message (string): A message to process
ctx (Context): MCP Context object (automatically injected)

Returns: Information about the context and processing

Prompts

1. weather_report

Generate weather report prompts for specified cities.

Arguments:

city (string): City name for the weather report
format (string): Report format ("brief", "detailed", or "forecast")

2. calculation_helper

Generate prompts for mathematical calculations.

Arguments:

operation (string): Type of mathematical operation
context (string): Additional context for the calculation

Installation & Development

Using Virtual Environment (Recommended)

Create and activate virtual environment:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Unix/macOS:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Run in development mode:

python -m src.server --port 8000 --log-level DEBUG

Run tests:
```
pytest
```
Deactivate virtual environment when done:
```
deactivate
```

Without Virtual Environment (Not Recommended)

Install dependencies:
```
pip install -r requirements.txt
```

Run in development mode:

python -m src.server --port 8000 --log-level DEBUG

Run tests:
```
pytest
```

Direct Execution

The server supports direct execution for development and testing:

# Basic execution
python src/server.py

# With custom options
python src/server.py --port 3000 --log-level DEBUG --json-response

Command-line options:

--port: Port to run the server on (default: 8000)
--log-level: Logging level (default: INFO)
--json-response: Use JSON responses instead of SSE streams

Container Deployment

Docker

Build the container:
```
docker build -t mcp-server .
```
Run the container:
```
docker run -p 8000:8000 mcp-server
```

With custom environment:

docker run -p 8000:8000 -e LOG_LEVEL=DEBUG mcp-server

Docker Compose

Basic deployment:
```
docker-compose up
```
With production nginx proxy:
```
docker-compose --profile production up
```

Kubernetes

Example deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
    spec:
      containers:
      - name: mcp-server
        image: mcp-server:latest
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-service
spec:
  selector:
    app: mcp-server
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

API Endpoints

Health Check

URL: GET /health
Response: Server health status and metadata
Use: Container orchestration health checks

Server Info

URL: GET /
Response: Server information, available tools, and prompts
Use: Discovery and documentation

MCP Endpoint

URL: POST /mcp
Protocol: MCP over HTTP (JSON-RPC 2.0)
Transport: Streamable HTTP with SSE support
Use: MCP client connections

Connection Details

For MCP Clients

Server URL: http://localhost:8000/mcp

Transport: Streamable HTTP

Authentication: None (can be extended)

Example Client Connection (Python)

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[tool.name for tool in tools.tools]}")
            
            # Call a tool
            result = await session.call_tool("get_weather", {"city": "New York"})
            print(f"Weather result: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Testing

Unit Tests

pytest tests/

Integration Tests

# Start the server
python -m src.server --port 8001 &
SERVER_PID=$!

# Test health endpoint
curl http://localhost:8001/health

# Test server info
curl http://localhost:8001/

# Test MCP connection with a client
# (see example above)

# Cleanup
kill $SERVER_PID

Container Tests

# Test container build
docker build -t mcp-server-test .

# Test container run
docker run -d -p 8002:8000 --name mcp-test mcp-server-test

# Test health check
curl http://localhost:8002/health

# Cleanup
docker stop mcp-test && docker rm mcp-test

Monitoring

Health Checks

The server provides a /health endpoint that returns:

Server status
Tool and prompt counts
Transport information

Logging

Structured logging with configurable levels:

# Set log level via environment
export LOG_LEVEL=DEBUG
python -m src.server

# Or via command line
python -m src.server --log-level DEBUG

Metrics

For production deployments, consider adding:

Prometheus metrics endpoint
OpenTelemetry tracing
Request/response logging

Architecture

┌─────────────────┐    HTTP/SSE     ┌─────────────────┐
│   MCP Client    │ ◄──────────────► │   MCP Server    │
│                 │                 │                 │
│ - Claude Code   │                 │ - Tools         │
│ - Custom Client │                 │ - Prompts       │
│ - Web App       │                 │ - Health Check  │
└─────────────────┘                 └─────────────────┘
                                           │
                                           ▼
                                    ┌─────────────────┐
                                    │   Container     │
                                    │                 │
                                    │ - Docker        │
                                    │ - Kubernetes    │
                                    │ - Cloud Run     │
                                    └─────────────────┘

Security Considerations

The server runs as a non-root user in containers
No secrets or API keys are required for basic functionality
Consider adding authentication for production deployments
Network policies should restrict access to necessary ports only

Contributing

Fork the repository
Create a feature branch
Make changes with tests
Run the test suite
Submit a pull request

License

This project is available under the MIT License.

Container MCP Server

Features

HTTP Transport: Uses streamable HTTP transport for remote MCP server deployment
Container Ready: Optimized for Docker/Kubernetes deployment with health checks
Simple Tools: Weather data, mathematical calculations, and context-aware operations
Prompts: Reusable templates for weather reports and calculations
No External Dependencies: Mock data for easy testing and demonstration

Tools

1. get_weather

Get mock weather information for a city.

Parameters:

city (string, optional): City name (default: "San Francisco")

Returns: Weather data including temperature, condition, and humidity

2. sum_numbers

Add two numbers together.

Parameters:

a (float): First number
b (float): Second number

Returns: The sum of the two numbers

3. context_info

Demonstrate MCP context capabilities including logging, progress reporting, and metadata access.

Parameters:

message (string): A message to process
ctx (Context): MCP Context object (automatically injected)

Returns: Information about the context and processing

Prompts

1. weather_report

Generate weather report prompts for specified cities.

Arguments:

city (string): City name for the weather report
format (string): Report format ("brief", "detailed", or "forecast")

2. calculation_helper

Generate prompts for mathematical calculations.

Arguments:

operation (string): Type of mathematical operation
context (string): Additional context for the calculation

Installation & Development

Using Virtual Environment (Recommended)

Create and activate virtual environment:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Unix/macOS:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Run in development mode:

python -m src.server --port 8000 --log-level DEBUG

Run tests:
```
pytest
```
Deactivate virtual environment when done:
```
deactivate
```

Without Virtual Environment (Not Recommended)

Install dependencies:
```
pip install -r requirements.txt
```

Run in development mode:

python -m src.server --port 8000 --log-level DEBUG

Run tests:
```
pytest
```

Direct Execution

The server supports direct execution for development and testing:

# Basic execution
python src/server.py

# With custom options
python src/server.py --port 3000 --log-level DEBUG --json-response

Command-line options:

--port: Port to run the server on (default: 8000)
--log-level: Logging level (default: INFO)
--json-response: Use JSON responses instead of SSE streams

Container Deployment

Docker

Build the container:
```
docker build -t mcp-server .
```
Run the container:
```
docker run -p 8000:8000 mcp-server
```

With custom environment:

docker run -p 8000:8000 -e LOG_LEVEL=DEBUG mcp-server

Docker Compose

Basic deployment:
```
docker-compose up
```
With production nginx proxy:
```
docker-compose --profile production up
```

Kubernetes

Example deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
    spec:
      containers:
      - name: mcp-server
        image: mcp-server:latest
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-service
spec:
  selector:
    app: mcp-server
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

API Endpoints

Health Check

URL: GET /health
Response: Server health status and metadata
Use: Container orchestration health checks

Server Info

URL: GET /
Response: Server information, available tools, and prompts
Use: Discovery and documentation

MCP Endpoint

URL: POST /mcp
Protocol: MCP over HTTP (JSON-RPC 2.0)
Transport: Streamable HTTP with SSE support
Use: MCP client connections

Connection Details

For MCP Clients

Server URL: http://localhost:8000/mcp

Transport: Streamable HTTP

Authentication: None (can be extended)

Example Client Connection (Python)

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[tool.name for tool in tools.tools]}")
            
            # Call a tool
            result = await session.call_tool("get_weather", {"city": "New York"})
            print(f"Weather result: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Testing

Unit Tests

pytest tests/

Integration Tests

# Start the server
python -m src.server --port 8001 &
SERVER_PID=$!

# Test health endpoint
curl http://localhost:8001/health

# Test server info
curl http://localhost:8001/

# Test MCP connection with a client
# (see example above)

# Cleanup
kill $SERVER_PID

Container Tests

# Test container build
docker build -t mcp-server-test .

# Test container run
docker run -d -p 8002:8000 --name mcp-test mcp-server-test

# Test health check
curl http://localhost:8002/health

# Cleanup
docker stop mcp-test && docker rm mcp-test

Monitoring

Health Checks

The server provides a /health endpoint that returns:

Server status
Tool and prompt counts
Transport information

Logging

Structured logging with configurable levels:

# Set log level via environment
export LOG_LEVEL=DEBUG
python -m src.server

# Or via command line
python -m src.server --log-level DEBUG

Metrics

For production deployments, consider adding:

Prometheus metrics endpoint
OpenTelemetry tracing
Request/response logging

Architecture

┌─────────────────┐    HTTP/SSE     ┌─────────────────┐
│   MCP Client    │ ◄──────────────► │   MCP Server    │
│                 │                 │                 │
│ - Claude Code   │                 │ - Tools         │
│ - Custom Client │                 │ - Prompts       │
│ - Web App       │                 │ - Health Check  │
└─────────────────┘                 └─────────────────┘
                                           │
                                           ▼
                                    ┌─────────────────┐
                                    │   Container     │
                                    │                 │
                                    │ - Docker        │
                                    │ - Kubernetes    │
                                    │ - Cloud Run     │
                                    └─────────────────┘

Security Considerations

The server runs as a non-root user in containers
No secrets or API keys are required for basic functionality
Consider adding authentication for production deployments
Network policies should restrict access to necessary ports only

Contributing

Fork the repository
Create a feature branch
Make changes with tests
Run the test suite
Submit a pull request

License

This project is available under the MIT License.