Secure Python Agent + MCP (mTLS + OPA)

Portable reference deployment: Docker Compose works on a laptop or Linux VM. Kubernetes manifests are intentionally a later deployment adapter; the application and policy model do not depend on Docker.

Security design

• Nginx terminates external mTLS and validates client certificates against the configured CA.

• Nginx overwrites X-Client-Cert with its verified peer certificate.

• MCP app is not published; only Nginx can reach it on a private Docker network.

• The app independently checks certificate validity, CA signature, clientAuth EKU and exact URI SAN.

• OPA makes fail-closed per-tool authorization decisions.

• Agent private key is mounted at runtime, never copied into an image.

This proxy-header trust design assumes the MCP container is reachable ONLY from the trusted Nginx container. Do not publish MCP/OPA ports, do not attach untrusted workloads to the backend network, and do not trust client-supplied identity headers. For higher assurance, use mTLS between Nginx and MCP too, or terminate mTLS directly in an ASGI server that exposes verified peer certificates.

Related MCP server: MCP Tool Manager

Quick start (development only)

Requires Docker Engine + Compose plugin and OpenSSL.

chmod +x scripts/*.sh
./scripts/generate-dev-pki.sh
cp .env.example .env
docker compose -f deployment/docker/docker-compose.yml up --build -d

The demo endpoint is https://localhost:8443/mcp. The demo CA key is intentionally created locally and MUST NOT be used in production.

Test TLS:

./scripts/test-mtls.sh

Install client dependencies locally and run:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements-client.txt
python agent/mcp_client.py

Production adaptation

1. Use offline Root CA + online Intermediate CA, SPIRE X.509-SVID, or a managed PKI.

2. Issue a server certificate with the real DNS name in SAN.

3. Issue a client certificate with one exact SPIFFE URI SAN, e.g. spiffe://your-trust-domain/agent/primary.

4. Configure MCP_EXPECTED_SPIFFE_ID, MCP_ALLOWED_HOSTS, and OPA policies.

5. Store keys in SPIRE Workload API / Vault / cloud KMS-backed secret manager.

6. Implement renewal and revocation/trust-bundle refresh. Short lifetime alone is not instant revocation.

7. Restrict firewall to the gateway port; protect SSH and Docker daemon.

8. Enable TLS/mTLS on proxy-to-app hop for higher assurance.

9. Add rate limits, request size limits, metrics, log shipping, backups, and incident response.

Integrating your existing project

Keep your LLM and orchestration code. Replace its MCP transport setup with the pattern in agent/mcp_client.py, using your actual endpoint and runtime-delivered certificate/key. Replace demo tool bodies in app/tools/ with your existing business logic. Every tool must call authorize_tool() server-side before performing side effects. Never let the LLM or client decide authorization.

Notes

This is a reference scaffold. Pin dependency versions after validating them in your environment and CI. MCP SDK APIs evolve; verify the pinned SDK transport API before upgrading. The included tests cover certificate parsing/identity and OPA policy behavior; run the end-to-end TLS tests after starting the stack.