Skip to content

caddy-mcp

Caddy reverse-proxy API + MCP Server for the agent-utilities ecosystem — a typed, deterministic tool surface over the Caddy Admin API for configuration, PKI, and reverse-proxy management.

Official documentation

This site is the canonical reference for caddy-mcp, maintained alongside every release.

PyPI MCP Server License GitHub

Overview

caddy-mcp wraps the Caddy Admin API (the live configuration endpoint Caddy exposes on :2019) with typed, deterministic MCP tools and a Pydantic-AI agent. It provides:

  • Api — a requests-based REST facade over the Caddy Admin API, organized by capability (configuration traversal, @id-tagged objects, config adaptation, PKI, reverse-proxy upstreams).
  • MCP tools — action-dispatch tools for config, pki, and reverse_proxy, surfaced to any MCP client or policy router.
  • An A2A agent server — the caddy-agent console script exposes the same capability as a conversational Pydantic-AI agent.

Explore the documentation

  • Installation — pip, source, extras, and the prebuilt Docker image.
  • Deployment — run the MCP and agent servers, Docker Compose, Caddy + Technitium.
  • Usage — the MCP tools, the Api client, and the agent.
  • Backing Platform — deploy Caddy with Docker and connect the Admin API.
  • Overview — the integration architecture and tool surface.
  • Concepts — the CONCEPT:CADDY-* registry.

Quick start

pip install "caddy-mcp[mcp]"
caddy-mcp                        # stdio MCP server (default transport)

Point it at a running Caddy Admin API:

export CADDY_URL=http://localhost:2019
caddy-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server, reverse proxy, DNS).