MCP Server Project

A secure Model Context Protocol (MCP) server providing HTTP endpoints for AI agent tool execution. Built with Python 3.12+, Starlette, and FastMCP.

Quick Start

# Clone and setup
git clone https://github.com/sdirishguy/mcp_server_project.git
cd mcp_server_project
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Run server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Test
curl http://localhost:8000/health

Docker

docker-compose up -d
curl http://localhost:8000/health

Configuration

Required environment variables:

JWT_SECRET="your-secret-key-32-chars-minimum"    # Required for production
ADMIN_USERNAME="admin"                            # Default admin user
ADMIN_PASSWORD="secure-password"                  # Change from default

Optional configuration:

SERVER_PORT=8000
MCP_BASE_WORKING_DIR="./shared_host_folder"
ENVIRONMENT="development"                         # development|staging|production
ALLOW_ARBITRARY_SHELL_COMMANDS="false"           # Security: disabled by default
CORS_ORIGINS="http://localhost:3000,https://yourdomain.com"

# API Keys for LLM tools
OPENAI_API_KEY="sk-..."
GEMINI_API_KEY="..."

Authentication

Get a token:

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

Use token:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/protected

Available Tools

API Endpoints

• GET /health - Health check

• GET /metrics - Prometheus metrics

• POST /api/auth/login - Authentication

• POST /mcp/mcp.json/ - MCP JSON-RPC (requires auth)

• POST /api/adapters/{type} - Create data adapters

• GET /docs - Interactive API documentation

Security Features

• JWT-based authentication with configurable providers

• Path traversal prevention for file operations

• Shell command filtering and sandboxing

• Rate limiting on authentication endpoints

• Security headers (HSTS, CSP, etc.)

• CORS configuration

• Audit logging for all operations

Development

Run tests:

pytest -q  # 53 passing, 21 skipped (FastMCP lifespan issue)

Testing

Run tests: pytest -q (53 passing, 21 skipped due to FastMCP lifespan integration)

The skipped tests require proper ASGI lifespan management which TestClient doesn't provide by default. Production server works correctly.

Linting:

pre-commit install
pre-commit run --all-files

Production Deployment

1. Set strong JWT_SECRET (32+ characters)

2. Change default ADMIN_PASSWORD

3. Set ENVIRONMENT=production

4. Configure appropriate CORS_ORIGINS

5. Use HTTPS termination at load balancer

6. Monitor /health and /metrics endpoints

See PRODUCTION_READINESS_REPORT.md for detailed checklist.

Architecture

• FastMCP: Tool execution via Model Context Protocol

• Starlette: Async web framework with middleware

• Pydantic: Configuration management and validation

• Prometheus: Metrics collection

• JWT: Stateless authentication

• Audit Logging: Structured event logging

License

MIT