Cloudflare MCP

Portal-safe Cloudflare MCP server for MADPANDA3D.

This service is built for the MAD MCP Portal access path. Agents should call it through the portal broker, not directly. Every MCP tool call must include the portal grant header. Cloudflare credentials should be supplied by the broker with x-cloudflare-api-token; local CLOUDFLARE_API_TOKEN is only a fallback. MCP protocol requests are rejected fail-closed when X-MADPANDA-PORTAL-GRANT is missing or does not match MCP_PORTAL_GRANT_TOKEN; /health remains unauthenticated for routing and container smoke checks.

Runtime

• Python 3.12
• FastMCP HTTP transport at /mcp
• Health route at /health
• Docker Compose service: cloudflare-mcp
• Container name: cloudflare-mcp
• Network: external mcp-network
• Public hostname: cfmcp.madpanda3d.com

Required Headers

Header	Required	Purpose
X-MADPANDA-PORTAL-GRANT	Yes	Must match MCP_PORTAL_GRANT_TOKEN; gates access to every tool call.
x-cloudflare-api-token	Yes for Cloudflare API calls	Cloudflare Bearer token for the current user/account. Falls back to CLOUDFLARE_API_TOKEN if configured.
x-cloudflare-account-id	Optional	Default account scope hint for agents and workflows.
x-cloudflare-zone-id	Optional	Default zone scope hint for agents and workflows.

Environment

Copy .env.example to .env for local/container deployment and fill in only real deployment values. Set MCP_EXPECT_PORTAL_CLOUDFLARE_TOKEN=true when the portal supplies Cloudflare credentials through broker headers. Never commit .env.

Tools

• check_configuration: validates portal/provider setup without exposing secrets.
• list_capabilities: lists tool groups, risk levels, and common workflows.
• get_endpoint_coverage: queries the generated Cloudflare endpoint matrix.
• get_tool_usage: explains safe usage and side effects for each tool.
• cloudflare_api_request: guarded generic Cloudflare REST API request tool.

cloudflare_api_request covers the stable Cloudflare REST operations present in the official Cloudflare OpenAPI schema. Mutating methods require confirm_write=true; destructive methods and schema-classified destructive operations also require confirm_destructive=true.

Local Development

uv is preferred when available:

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy

Fallback with the system Python:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
ruff check .
mypy

Run locally:

cloudflare-mcp
curl http://127.0.0.1:8000/health

Docker

docker-compose up -d --build cloudflare-mcp
docker-compose ps
curl http://127.0.0.1:8000/health

The compose file intentionally exposes the service only on mcp-network for nginx-proxy-manager or MAD MCP Portal routing.

Public routing target:

https://cfmcp.madpanda3d.com/mcp -> nginx-pm -> cloudflare-mcp:8000

Endpoint Coverage

Coverage is generated from Cloudflare's official OpenAPI schema repository: https://github.com/cloudflare/api-schemas.

Regenerate:

curl -L --fail --silent --show-error \
  -o /tmp/cloudflare-openapi.json \
  https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.json
python scripts/build_endpoint_coverage.py /tmp/cloudflare-openapi.json

See docs/endpoint-coverage.md for the generated matrix.