sentra-mcp

Minimal MCP-ready service built with FastAPI. It exposes a health endpoint, a discovery endpoint for tools, and an execution endpoint wired to two simple tools (ping, time). The service is designed to run locally (uvicorn), inside Docker, or on an OVH VPS behind a TLS-enabled reverse proxy.

Features

• FastAPI server with optional Bearer authentication (MCP_AUTH_TOKEN).
• /health, /tools, /tools/execute endpoints.
• NDJSON request logging middleware for easy ingestion by log processors.
• Modular tool registry ready for future additions (git, files, n8n, RAG, RBAC, metrics).
• Dockerfile based on python:3.12-slim and Docker Compose profile exposing port 8400.
• .env management with python-dotenv for local runs.

Repository Layout

• mcp/ – application package (main.py, config, middleware, tools).
• docker/ – container builds (Dockerfile, Caddyfile for TLS reverse proxy).
• requirements.txt – Python dependencies.
• .env.example – template for sensitive configuration.
• docker-compose.yml – brings up the API + optional Caddy reverse proxy.
• .gitignore – ignores Python caches, env files, and other generated assets.

Local Development

1. Create and activate a virtualenv; install dependencies.

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

2. Copy .env.example to .env and adjust values.
3. Launch the API.

   uvicorn mcp.main:app --host 0.0.0.0 --port 8400 --reload
   

4. Test the endpoints (replace TOKEN if MCP_AUTH_TOKEN is set).

   curl -fsSL http://localhost:8400/health
   curl -fsSL -H "Authorization: Bearer TOKEN" http://localhost:8400/tools
   curl -fsSL -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"ping","payload":{"message":"hello"}}' \
     http://localhost:8400/tools/execute
   

Docker & Compose

cp .env.example .env
# Build and launch the stack (API + optional Caddy proxy)
docker compose up --build

• The API is served on http://localhost:8400.
• When the reverse-proxy service is enabled, the HTTPS endpoint is https://localhost:8443 with certificates generated by Caddy on first run.

Healthcheck & Restart

The Compose file defines a healthcheck hitting /health every 30 seconds and uses restart: unless-stopped to keep the service online.

VPS Preparation Checklist

Run these steps on the OVH VPS before deploying:

1. Inspect resources.

   lscpu | egrep 'Model name|CPU\(s\)'
   free -h
   df -h /
   

2. Docker resource usage.

   docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
   docker system df
   

3. Prune unused artifacts. Review before confirming.

   docker container prune
   docker image prune
   docker volume prune
   docker network prune
   docker system prune
   

4. Remove conflicting services/ports.

   sudo ss -tulpn | grep ':8400'
   sudo systemctl disable --now <legacy-service>
   

5. Update packages + reboot if required.

   sudo apt update && sudo apt upgrade -y
   sudo reboot
   

Reverse Proxy with TLS (Caddy)

• docker/Caddyfile configures Caddy as an HTTPS reverse proxy for the API.
• Set the DOMAIN environment variable before running Compose to request real certificates via ACME (Caddy handles LetsEncrypt automatically).
• For Cloudflare tunnel alternatives, swap the proxy container with your tunnel config and continue to terminate TLS at Cloudflare.

Firewall & OVH Network

1. Configure the OVH control panel firewall to allow only the required IP ranges (your office, CI runners, ChatGPT connectors).
2. On the VPS, restrict ports with UFW (example):

   sudo ufw default deny incoming
   sudo ufw allow from <trusted-ip>/32 to any port 22 proto tcp
   sudo ufw allow from <trusted-ip>/32 to any port 80,443 proto tcp
   sudo ufw enable
   

3. Document the allowed IP list to keep parity between the OVH panel and the VPS firewall.

Validation (Local or VPS)

1. docker compose up --build (or deploy stack on VPS).
2. Check logs for NDJSON output (one entry per request).
3. Validate endpoints:

   curl -fsSL http://<host>:8400/health
   curl -fsSL -H "Authorization: Bearer TOKEN" http://<host>:8400/tools
   curl -fsSL -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"time"}' \
     http://<host>:8400/tools/execute
   

4. Run docker ps and ensure only the MCP stack services are exposed.
5. Monitor resource usage (htop, docker stats) for stability.

ChatGPT Developer Mode Integration

1. Expose the MCP HTTPS endpoint publicly (DNS record -> proxy -> VPS port 8400).
2. Verify valid TLS certificate (LetsEncrypt or Cloudflare).
3. In ChatGPT → Connectors → Developer Mode, add the new server URL.
4. Confirm the ping and time tools show up and respond to execution tests.

Future Enhancements

• Implement rich tools: git.commit_push, files.write, n8n.trigger, doc.index, doc.query, ...
• Add a lightweight vector store (Chroma/FAISS) and CPU embeddings for local RAG.
• Introduce RBAC, per-token quotas, and metrics exporters (Prometheus/OpenTelemetry).
• Harden reverse proxy (rate limiting, mTLS for internal hops, WAF in front of Caddy/NGINX).
• Automate VPS provisioning with Terraform + Ansible for repeatable deployments.