@yawlabs/caddy-mcp
Manage Caddy web servers through the admin API — config, routes, reverse proxies, TLS/PKI, metrics, and snapshots.
Read, write, delete, and atomically load Caddy configuration at arbitrary JSON paths or by
@id.Create, list, update, and remove HTTP routes and reverse proxy entries, optionally using stable IDs for idempotent updates.
Convert Caddyfile or supported adapter configs to Caddy JSON without applying them.
Inspect and configure TLS settings, including ACME email/CA/profile and ECH status, plus query PKI CA info and certificate chains.
Check Caddy connectivity/status, list servers, inspect upstream health, and read or filter Prometheus metrics.
Save, list, and restore configuration snapshots for rollback.
Gracefully stop Caddy and require confirmation for destructive operations.
Manage Caddy web servers: config, routes, reverse proxies, TLS, PKI, metrics, snapshots via Caddy's admin API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@yawlabs/caddy-mcp Proxy api.local to localhost:3000"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@yawlabs/caddy-mcp
One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Tested with Yaw MCP 1.1.13 or newer. Or install manually below.
Manage Caddy web servers from Claude Code, Cursor, and any MCP client. 18 tools + 4 resources covering every endpoint in Caddy's admin API reference — config, routes, reverse proxies, TLS, PKI, metrics, snapshots.
Built and maintained by Yaw Labs.
Why this one?
Other Caddy MCP servers wrap half the admin API and silently swallow errors. This one doesn't.
Complete admin API coverage — every endpoint in Caddy's admin API reference:
/load,/config/*,/id/*,/stop,/adapt,/pki/ca/*,/reverse_proxy/upstreams,/metrics. No placeholder tools that 404. Caddy's Go runtime debug endpoints (/debug/pprof/*,/debug/vars) are deliberately not wrapped — for leak trends usecaddy_metricswithfilter: "go_goroutines"or"go_memstats", which come from the same admin registry; for stack dumps, CPU profiles and traces, curl the admin endpoint directly (Caddy profiling docs).Safe concurrent writes — uses ETags (
If-Match) so your changes never silently overwrite someone else's. SurfacesHTTP 412 Precondition Failedas a clear message, not a cryptic error.Safe-by-default mutations —
caddy_config_setdefaults to idempotentoverwrite(PATCH), notappend(POST). Calling twice doesn't duplicate your route. A write to the config root — which replaces the entire config, admin endpoint included — is refused withoutconfirm=trueand snapshotted first, likecaddy_load.Defensive parsing —
caddy_list_routesnever crashes on malformed config, even if routes are null, handlers are strings, or matchers are non-arrays. Regression-tested.No leaked credentials in errors — if
CADDY_ADMIN_URLcontains a token in the path/query, the connect-failed message shows only the origin.Fallback error surfacing — when a TLS write PATCH fails and the PUT fallback also fails, both error bodies are returned so you know what actually went wrong.
Tool annotations — every tool declares
readOnlyHint,destructiveHint, andidempotentHint, so MCP clients can skip confirmations for safe ops.Instant startup — ships as a single bundle with two runtime deps (the MCP SDK + Zod). No 5-minute
node_modulesinstall.Input hardening — adapter names,
@idvalues, server names, and CA ids are all regex-validated with length caps. Blocks CRLF header injection and ReDoS.
Related MCP server: cognigy-ai-mcp-management-server
Quick start
1. Enable the Caddy admin API
Caddy ships with the admin API enabled on localhost:2019 by default. If you're running Caddy in Docker or on a remote host, expose it via CADDY_ADMIN_URL.
2. Create .mcp.json in your project root
macOS / Linux / WSL:
{
"mcpServers": {
"caddy": {
"command": "npx",
"args": ["-y", "@yawlabs/caddy-mcp@latest"]
}
}
}Windows:
{
"mcpServers": {
"caddy": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@yawlabs/caddy-mcp@latest"]
}
}
}Why the extra step on Windows? Since Node 20,
child_process.spawncannot directly execute.cmdfiles (that's whatnpxis on Windows). Wrapping withcmd /cis the standard workaround. This file is safe to commit — it contains no secrets.
3. Restart and approve
Restart Claude Code (or your MCP client) and approve the Caddy MCP server when prompted.
That's it. Now ask your AI assistant:
"Proxy api.local to localhost:3000"
"What routes are configured on srv0?"
"Show me the Prometheus metrics"
Configuration
Environment variable | Default | Description |
|
| Caddy admin API URL. Set to |
| (none) | Optional Bearer token, sent as |
| (none) | Directory for persisting |
|
| Number of retries on transient failures: network errors, and 502/503/504 (which only a proxy in front of Caddy sends). Caddy's own 500s are deterministic rejections and never retry, nor do 4xx and 412. Requests a replay could change the outcome of also skip retry: POSTs to |
|
| Timeout in ms for admin API requests that do not change the config: GETs, |
|
| Timeout in ms for every request that changes the config: |
Unix socket admin endpoints:
Caddy's recommended hardening is to move the admin API off a loopback port and onto a unix socket, where access is governed by filesystem permissions:
{
admin unix//var/run/caddy-admin.sock
}Point CADDY_ADMIN_URL at the same path (unix:///var/run/caddy-admin.sock)
and requests are sent over the socket instead of TCP. The process running
caddy-mcp needs read/write permission on the socket file. Leave
CADDY_API_TOKEN unset here unless an authenticating proxy actually listens on
that socket: over a unix path caddy-mcp is usually talking to Caddy's own
socket, where the token does nothing — and, before Caddy 2.11.3, is logged in
clear.
Runtime (oam or Node):
The caddy-mcp command prefers oam when it finds a usable
one and otherwise runs on Node. It never serves on an oam older than 0.20.2.
Environment variable | Default | Description |
|
|
|
| (unset) |
|
| (unset) | Path to the oam binary to use. Otherwise the launcher checks |
An outdated oam is fixed with oam self-update. Under Yaw MCP, which runs servers
on oam by default, yaw-mcp set <namespace> runtime=node switches this server to
Node.
Alternate MCP clients:
Client | Config file |
Claude Code |
|
Claude Desktop |
|
Cursor |
|
Windsurf |
|
VS Code |
|
Use the same JSON block shown above in any of these.
Tools
Config management (6)
caddy_config_get — Read config at any JSON path (or the full config).
caddy_config_set — Write config at a path. Modes:
overwrite(PATCH, default, idempotent; the key must exist, and the whole subtree at the path is replaced),append(POST: appends to an array, but replaces an existing non-array key and cannot create missing parents),insert(PUT: inserts at an array position, or strictly creates a key along with any missing parents and fails with 409 if it exists — the way to create a server or app, even on an instance with no config).appendat a path ending in/...(e.g.apps/http/servers/srv0/routes/...) with an array value appends every element in one request — all or nothing, one reload; without the/..., an array value is added as a single element and Caddy rejects the load for typed arrays likeroutesorlisten. A path that addresses the config root ('','/','config','/config/', a slash-only variant, or any of those followed by a lone...segment) addresses the entire config and requiresconfirm=true:overwriteandappendthere replace the whole configuration withvalue, exactly ascaddy_loadwould, including theadminblock unlessvaluecarries one — after which Caddy re-binds its admin endpoint to the new config'sadmin.listen, to its default address when it sets none, or to no address at all when it setsadmin.disabled, and aCADDY_ADMIN_URLpointing anywhere else stops working. A root write auto-snapshots the prior config first (when it can be read) socaddy_revertcan restore it; no other path is snapshotted.insertat the root only succeeds after a rootcaddy_config_delete(409 otherwise), andoverwriteis the reverse: after a root delete it answers 404 untilappend,insertorcaddy_loadre-creates the config.caddy_config_delete — Delete config at a path. Requires
confirm=true(deleting a parent path also removes every descendant). A path that addresses the config root ('','/','config','/config/', a slash-only variant, or any of those followed by a lone...segment) addresses the entire config: it unloads every app and server plus theadminblock, after which Caddy re-binds its admin endpoint to its default address (localhost:2019, or$CADDY_ADMINin Caddy's environment) — ifCADDY_ADMIN_URLpoints anywhere else, neither caddy-mcp norcaddy_revertcan reach Caddy afterwards. A root delete auto-snapshots the prior config first (when it can be read), socaddy_revertcan restore it while Caddy is still reachable; no other path is snapshotted. To replace the config rather than unload it, usecaddy_load.caddy_config_by_id — Get/set/delete config by
@idtag — much easier than navigating deep paths. Thedeleteaction requiresconfirm=true. Everysetanddeletefirst asks Caddy where theidresolves, and refuses one that does not resolve inside the config tree. If it resolves to the config root — normally because it is the config's own top-level@id, string or number — it names the entire config:setanddeletewith no subpath (or a lone...) then replace or unload the whole configuration, exactly as a rootcaddy_config_set/caddy_config_deletedoes — both requireconfirm=true, snapshot the prior config first, and report where the admin endpoint went. A subpath inside it is an ordinary write.caddy_load — Replace the entire config atomically. Runs on
CADDY_LOAD_TIMEOUT(55 seconds by default), like every config change. Auto-snapshots the prior config, and keeps that snapshot when the load times out with its outcome unknown. Lists the Caddyfile adapter's warnings, and reports a load that failed as an error even when Caddy answered HTTP 200 — which Caddy 2.11.4 does for a Caddyfile that adapted with warnings (caddyserver/caddy#7246).formatisjson(default) orcaddyfile; stock Caddy registers only thecaddyfileadapter, so for any other adapter compiled into a custom build, adapt first withcaddy_adaptand load the JSON (the Atomic deploy example below).caddy_revert — Manage config snapshots for rollback. Actions:
list,save,apply(confirm-gated). In-memory, last 10. Auto-captured beforecaddy_load, and before acaddy_config_delete,caddy_config_setorcaddy_config_by_idthat addresses the config root. Anapplythat times out with its outcome unknown keeps the pre-revert config as snapshot [0], which shifts every older snapshot down one index; the error says where the target now sits.
Route operations (4)
caddy_reverse_proxy — Add a reverse proxy in one call:
from='api.local' to=['localhost:3000']. Pass an optionalidfor idempotent writes — repeat calls replace the route in place instead of duplicating.caddy_add_route — Add a route with full match/handle control (any Caddy handler).
caddy_remove_route — Remove a route by
@id(preferred) or by index. Requiresconfirm=true.caddy_list_routes — Human-readable route summary. Defensive: never crashes on weird config.
TLS & config conversion (2)
caddy_tls — Check or set TLS settings. Actions:
status,set_email(ACME email),set_acme_ca(ACME CA URL),set_acme_profile(ACME profile, Caddy 2.10+ — experimental upstream: the ACME profiles spec is still a draft and Caddy marks the field subject to change. Caddy accepts any profile name on load, so a name the CA does not advertise fails only at issuance, in Caddy's own logs), and the read-onlyech_status(the Encrypted ClientHello config atapps/tls/encrypted_client_hello, Caddy 2.10+). The set actions PATCH first; whenapps/tlsis not set they PUT a minimal config, which also creates any missing parents, so they work on an instance with no config at all. On an existing config they deep-merge into the issuer path and PATCH the result back, preserving siblings (custom certs,on_demand, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.caddy_adapt — Convert a config in any registered adapter format to Caddy JSON without applying it.
caddyfile(built-in, default) plus any adapter module compiled into your Caddy binary — e.g.,nginx(caddy-nginx-adapter),yaml(caddy-yaml). Great for previewing or porting from existing configs. One caveat on Caddy 2.11.4 and earlier: a Caddyfileorderglobal option is not preview-only. It mutates that Caddy process's directive order, so it carries into later Caddyfile adapts and loads in the same process, and anorderline that fails still removes the directive it names (caddyserver/caddy#7995, fixed upstream but unreleased as of 2.11.4).
Server operations (6)
caddy_status — Connectivity check + config summary (server count, routes, TLS mode). The TLS label replays Caddy's own automatic-HTTPS rule over the stored config instead of guessing from the listen port, so it reads
enabled,enabled (no listener gets TLS: all are on the HTTP port),auto (HTTPS),auto (HTTPS: host matchers on a non-HTTP port),mixed (TLS on non-HTTP listeners only),off (HTTP only),off (no host matchers),off (automatic HTTPS disabled)oroff (empty tls_connection_policies). The two qualifiedenabledreadings come from Caddy deciding TLS per socket rather than per server (app.go:535): connection policies are ignored on the HTTP-port listener, so a server that binds only that port is configured for TLS and serves none of it.caddy_list_servers — List all HTTP servers with names, addresses, route counts, and TLS status. Same labels as
caddy_status, but this tool reads onlyapps/http/serversand so assumes the defaulthttp_port80 /https_port443 — on an instance with custom ports,caddy_statusis the one that gets the label right.caddy_upstreams — Reverse proxy backend health, as Caddy's
/reverse_proxy/upstreamsarray returned verbatim. On Caddy 2.11.2+ this is not the configured upstream list: dynamic upstreams stay listed about 1 h after the dynamic source last returned them (so an address can outlive the config that referenced it), and a backend with requests in flight can appear twice when its resolved address differs from the entry's dial text. The extra copy always showsfails 0and repeatsnum_requests— do not sumnum_requestsacross entries.caddy_metrics — Prometheus metrics (request counts, durations, connections, TLS handshakes). Optional
filter(substring match on metric name, keeps# HELP/# TYPElines for retained metrics) andmax_lines(default 500) keep responses compact on busy servers.caddy_pki — CA info and certificate chains (default CA:
local).caddy_stop — Graceful shutdown. Requires
confirm=trueto prevent accidents.
Resources
Browsable read-only data — MCP clients can fetch these directly without a tool call:
caddy://config— Current full Caddy JSON configuration.caddy://servers— Summary of all configured HTTP servers.caddy://upstreams— Reverse proxy upstream health status, verbatim. Same 2.11.2+ caveat ascaddy_upstreams: lingering dynamic upstreams and duplicate in-flight entries; do not sumnum_requests.caddy://metrics— Prometheus metrics (text exposition format). Capped at the first 500 lines to keep client context bounded; use thecaddy_metricstool withfilter/max_linesfor filtered or larger output.
Examples
Add a reverse proxy
> "Proxy api.example.com to my app on port 3000"
→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"] })Idempotent reverse proxy (safe to re-run from automation)
> "Make sure api.example.com points at localhost:3000, with a stable id"
→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"], id: "api-prod" })
# First call creates the route under @id="api-prod".
# Subsequent calls with the same id REPLACE in place — no duplicate routes.
# Refuses with a clear error if "api-prod" is already in use by a non-route
# config object (TLS issuer, server, etc.) — @ids are config-global in Caddy.Filter Prometheus metrics
> "Just the HTTP request metrics, please"
→ caddy_metrics({ filter: "http_requests" })
# Keeps sample lines whose metric name contains "http_requests",
# plus their `# HELP` / `# TYPE` lines. Drops the rest.Preview a Caddyfile before applying it
> "Convert this Caddyfile to JSON so I can review it:
example.com {
reverse_proxy localhost:8080
}"
→ caddy_adapt({ config: "..." })Diagnose slow routes
> "Fetch Prometheus metrics and tell me which route is slowest"
→ caddy_metrics()Safely update a route by @id
> "Update the route with @id 'api-v2' to point to the new backend"
→ caddy_config_by_id({ id: "api-v2", action: "set", value: {...} })
# Uses ETags — you'll get HTTP 412 if someone else changed it firstAtomic deploy
> "Replace the whole config with this Caddyfile"
→ caddy_adapt({ config: "..." }) # validate first
→ caddy_load({ config: adaptedJson }) # apply atomicallyTroubleshooting
"Cannot connect to Caddy admin API"
Make sure Caddy is running.
caddy runorsystemctl status caddy.Check the admin endpoint. Default is
http://localhost:2019. If Caddy is in Docker, use the container hostname.Set
CADDY_ADMIN_URLin your MCP configenvto match.Over an SSH tunnel, map the same port on both ends (
ssh -L 2019:localhost:2019 <host>) and leaveCADDY_ADMIN_URLat its default. Caddy checks theHostheader against its own listen address, so a tunnel on a different local port answers403 host not allowed: localhost:<port>.Behind a reverse proxy, add the proxy's
host:portto the remote Caddy'sadmin.origins. Caddy checks bothHostandOrigin, and settingadmin.originsreplaces the defaultlocalhost/127.0.0.1/::1entries, so listlocalhost:2019too if local tools still need access. A non-loopback or wildcardadmin.listen— the Dockerhttp://caddy:2019above, for instance — does not allow an arbitraryHosteither, so it needsadmin.originsset as well.Pointing
CADDY_ADMIN_URLat Caddy's native remote admin listener (admin.remote, default:2021) fails before any HTTP is exchanged, because that listener requires a TLS client certificate and caddy-mcp does not present one. It surfaces as this message even though Caddy is running and accepted the connection.
"HTTP 412 Precondition Failed"
Someone (or something) changed the config between your read and your write.
The cached ETag has been invalidated. Re-read the config and retry.
"HTTP 401" or "HTTP 403" on any request
Caddy's own checks run on every admin request, reads included, and always answer with a JSON
{"error":...}body. If you got one, it is Caddy: theadmin.listen/admin.originsallowlists (host not allowed: ...,client is not allowed to access from origin ...,required Origin header is missing or invalid— see the tunnel and proxy bullets above), or, onadmin.remote, its mTLS identity and permission checks.A bodiless 401/403 came from something in front of Caddy — a proxy, a gateway, an SSO layer.
CADDY_API_TOKENapplies there and only there, so a missing or wrong token is one cause and the proxy's other access rules are another.Caddy's admin API has no bearer-token auth of its own, so setting
CADDY_API_TOKENwill not clear a 401/403 that carries a Caddy error body.
"directive 'X' is not an ordered HTTP handler" from caddy_adapt, or from caddy_load with format: "caddyfile"
Two causes, and Caddy's error cannot tell them apart:
The directive has no registered order — usually a plugin directive. Add an
orderglobal option, or wrap it in arouteblock.On Caddy 2.11.4 and earlier, an earlier failed or concurrent Caddyfile adaptation that used
orderin this same Caddy process removed that directive from the process-wide directive order. Restarting Caddy restores the default order (caddyserver/caddy#7995, unreleased).
The second cause is why a Caddyfile that adapted a minute ago can start failing with no edit to it. Caddy's own advice ("try … using the order global option") fixes the first cause and papers over the second.
SIGUSR1 / systemctl reload caddy stops reloading the Caddyfile
Expected, and not caused by a bug here. Since Caddy 2.11.1,
SIGUSR1reloads from the file on disk only if the config has never been changed through the admin API. The first write from caddy-mcp (or any other API client) makes Caddy consider the running config API-owned, andSIGUSR1becomes a no-op.Pick one owner per instance. If the Caddyfile is the source of truth, use caddy-mcp read-only tools (
caddy_status,caddy_list_routes,caddy_adapt) and reload from the file. If caddy-mcp owns the config, apply changes withcaddy_loadinstead ofSIGUSR1.One qualification on Caddy 2.11.4 and earlier:
caddy_adaptis read-only with respect to the config, but not with respect to the adapter. A Caddyfileorderglobal option changes that process's directive order, and a failedorderline can break later in-process adaptations — which is what aSIGUSR1reload andcaddy run --watchdo.caddy reload, which is what the packagedsystemctl reload caddyruns, adapts in the CLI process and is unaffected.
Windows: MCP server doesn't start
Use the
cmd /c npx ...pattern from the Quick start section. Node 20+ can't spawn.cmdfiles directly.
Requirements
Node.js 20+
Caddy 2.11.3 or later, with the admin API enabled (default:
localhost:2019). The latest 2.11.x is recommended; verified against Caddy 2.11.4. Two admin-side reasons for that floor:Caddy 2.11.2 and earlier log every admin request's headers at INFO, so if the
Authorizationheader fromCADDY_API_TOKENreaches the admin listener, the token is written to Caddy's log in plain text (caddyserver/caddy#7578).Caddy 2.11.1 and earlier accept a duplicate
@idsilently. A racingcaddy_reverse_proxycreate, or acaddy_config_by_idset withmode: "insert"on a route id, leaves two elements sharing one@id, and/id/resolves to only one of them.
Older 2.x mostly works, with two exceptions that both come from how Caddy sends its
ETag. Caddy 2.8.0 and later send it as a response header. Caddy 2.5.2 through 2.7.x send it as an HTTP trailer, which this client cannot read, and earlier versions send none. So before 2.8.0:the
If-Match(ETag) concurrency guard is inactive, because no ETag is ever cached to echo back;every
caddy_config_by_idsetanddeleteis refused, because the tool reads the ETag to learn where Caddy resolves the@idbefore it writes through it, and fails closed when it cannot.
The
@idwrite path relies onPATCHsemantics that the live integration suite pins per release.
Contributing
git clone https://github.com/YawLabs/caddy-mcp.git
cd caddy-mcp
npm install
npm run lint # Biome check
npm run lint:fix # Auto-fix
npm run build # tsup bundle
npm test # Vitest (782 unit tests, +39 POSIX-only unix-socket and launcher tests; +39 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
npm run typecheck # tsc --noEmitSee CONTRIBUTING.md for the full workflow, including release process.
License
MIT
Available Tools
18 toolscaddy_adaptARead-onlyIdempotent
Convert a config in any registered adapter format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs when Caddy is built with the matching adapter module ('caddyfile' is built-in; 'nginx', 'yaml', etc. require their adapter modules to be compiled into the Caddy binary). Returns the adapted JSON and any warnings separately. One exception to 'without loading it': on Caddy <= 2.11.4 a Caddyfile 'order' global option is not preview-only. It mutates that Caddy process's directive order, so it carries into every later Caddyfile adapt or load there, and an 'order' line that FAILS (unknown target, bad positional, extra arg) still removes the directive it names -- later Caddyfiles using that directive then fail with "directive 'X' is not an ordered HTTP handler" until another 'order' line re-places it or Caddy restarts. Fixed upstream in caddyserver/caddy#7995, unreleased as of v2.11.4.
Inputs: config (required), adapter.
caddy_add_routeA
Add a route with full control over match conditions and handlers. Supports any Caddy handler (reverse_proxy, file_server, static_response, redirect, encode, headers, etc.).
Inputs: match (required), handle (required), server, terminal.
caddy_config_by_idADestructive
Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects. The 'delete' action requires confirm=true. Every 'set' and 'delete' first asks Caddy where id resolves, and refuses an id that does not resolve inside the config tree (including an unknown one). If Caddy resolves id to the config ROOT -- normally because it is the config's own top-level '@id', string or number -- it names the ENTIRE config: 'set' and 'delete' with no subpath (or a lone '...') then act on the whole configuration exactly as caddy_config_set and caddy_config_delete do at the config root -- 'set' replaces it and 'delete' unloads it, the 'admin' block included, so Caddy's admin endpoint can move and CADDY_ADMIN_URL stop reaching it. Both then require confirm=true, snapshot the prior config first so caddy_revert can restore it, and report where the admin endpoint went. A subpath inside it (e.g. 'apps/http') is an ordinary write.
Inputs: id (required), mode, value, action, +2 more.
caddy_config_deleteADestructive
Delete config at a JSON path. Removes the config node at the specified path. Deleting a parent node also deletes every descendant -- e.g. deleting 'apps/http/servers/srv0' removes that server and all of its routes. Requires confirm=true. Any path that addresses the config ROOT ('', '/', 'config', '/config/', slash-only variants of those, or any of those followed by a lone '...' segment) addresses the ENTIRE config and unloads it: every app and server goes, and so does the 'admin' block, after which Caddy re-binds its admin endpoint to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment). If CADDY_ADMIN_URL points anywhere else, neither this server nor caddy_revert can reach Caddy afterwards. A root delete is snapshotted first, so caddy_revert can restore it while Caddy is still reachable; no other path is snapshotted. To REPLACE the config rather than unload it, use caddy_load.
Inputs: path (required), confirm.
caddy_config_getARead-onlyIdempotent
Read Caddy config at any JSON path. Returns the full config when path is empty, or a subtree at a specific path (e.g., 'apps/http/servers/srv0/routes').
Inputs: path.
caddy_config_setADestructive
Write config at a JSON path. Mode 'overwrite' (default) replaces the value at the path (PATCH) — idempotent, but it replaces the WHOLE subtree there: writing [] to '.../routes' drops every route. Mode 'append' (POST) adds to an array — NOT idempotent: calling twice with the same route duplicates it — but on a non-array key it REPLACES whatever is there, and it cannot create missing parent objects. Mode 'insert' (PUT) inserts at an array index (useful for route ordering), or strictly creates an object key together with any missing parents and fails with 409 if the key already exists — the safe way to create a server or app, including on an instance with no config at all. Any path that addresses the config ROOT ('', '/', 'config', '/config/', a slash-only variant, or any of those followed by a lone '...' segment) addresses the ENTIRE config and requires confirm=true: 'overwrite' and 'append' there REPLACE the whole configuration with value — Caddy runs it exactly as caddy_load would — so every app, server and route not in value is discarded, and so is the 'admin' block unless value carries one. Caddy then re-binds its admin endpoint to the new config's admin.listen, or to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment) when it sets none, or to no address at all when it sets admin.disabled; if CADDY_ADMIN_URL points anywhere else, neither this server nor caddy_revert can reach Caddy afterwards. A root write is snapshotted first, so caddy_revert can restore it while Caddy is still reachable; no other path is snapshotted. 'insert' at the root only succeeds after a root caddy_config_delete (Caddy answers 409 on any other instance, including one started with no config), and 'overwrite' is the reverse: after a root caddy_config_delete it answers 404 until 'append', 'insert' or caddy_load re-creates the config. To replace the whole config deliberately, caddy_load does the same thing behind the same gate and also accepts a Caddyfile.
Inputs: path (required), value (required), mode, confirm.
caddy_list_routesARead-onlyIdempotent
List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers, followed by the raw route JSON. Both halves are capped on large servers: the summary at 500 routes, the JSON at 20000 characters (truncated on whole-route boundaries, so it always parses). When either cap trims output, a note says how many routes were omitted -- read the rest with caddy_config_get at 'apps/http/servers//routes'.
Inputs: server.
caddy_list_serversARead-onlyIdempotent
List all configured HTTP servers with their names, listen addresses, route counts, and TLS status. Use this to discover server names before calling route tools.
Inputs: no named parameters.
caddy_loadADestructiveIdempotent
Replace the entire Caddy configuration atomically. Accepts a JSON config object, or a Caddyfile string with format='caddyfile'. This is the safest way to make large config changes. Runs on CADDY_LOAD_TIMEOUT (55 s by default), like every config change; a load that times out is not retried and may still apply, so re-read the config before loading again. Requires confirm=true: this DISCARDS the entire running config, including servers and routes not present in the supplied config. The prior config is snapshotted first and can be restored with caddy_revert.
Inputs: config (required), format, confirm.
caddy_metricsARead-onlyIdempotent
Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more. Output can be megabytes on busy servers -- use filter to keep only metrics whose name contains a substring (e.g. 'http_requests' or 'tls'); HELP/TYPE comment lines for retained metrics are kept. Filter-mode drops blank lines and free-form '# comment' lines, keeping only '# HELP'/'# TYPE' lines for matching metrics; the '# EOF' end-of-file marker is always preserved. Use max_lines to cap the response (default 500); a trailing comment reports how many lines were dropped.
Inputs: filter, max_lines.
caddy_pkiARead-onlyIdempotent
Get PKI certificate authority info or the CA certificate chain.
Inputs: ca, certificates.
caddy_remove_routeADestructive
Remove a route. Target by @id (preferred — stable across reorderings) or by array index on a specific server. Index-based removal is a two-step read-then-delete and can race against concurrent edits; prefer @id when possible. Only the @id mode is idempotent: a repeat call cannot remove a different route, it just reports the id as gone. The index mode is NOT — Caddy re-packs the routes array after a removal, so calling with index 2 twice removes TWO DIFFERENT routes. @ids are config-global in Caddy (NOT route-scoped): if id resolves to a non-route object (TLS issuer, server, etc.) the call refuses rather than deleting it.
Inputs: id, index, server, confirm.
caddy_reverse_proxyADestructive
Add a reverse proxy route. The most common operation — just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When id is OMITTED the route is appended to the server's routes array — calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When id is SUPPLIED the route is written via PATCH under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable id for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If id collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the server argument. Upstream scheme is honored: an https:// upstream gets a TLS transport and defaults to port 443, anything else is dialed in the clear. A to list that MIXES https:// and non-https entries is refused — the TLS transport applies to the whole handler, not per-upstream — so split those into two routes or use caddy_add_route.
Inputs: to (required), from (required), id, server.
caddy_revertADestructive
Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load, and before a caddy_config_delete or caddy_config_set at the config root (any path that addresses the whole config), and before a caddy_config_by_id set or delete whose @id resolves to the root with no subpath (or a lone '...'); no other delete or set is snapshotted. Last 10. By default they live in memory only and are LOST when this server restarts -- set CADDY_MCP_SNAPSHOT_DIR to a writable directory to persist them across restarts (they contain full Caddy configs, so pick the location deliberately). Actions: 'list' shows snapshots with timestamps, 'save' manually captures the current config, 'apply' restores a snapshot (requires confirm=true).
Inputs: action (required), index, confirm.
caddy_statusARead-onlyIdempotent
Check Caddy connectivity and get a config summary: servers, routes, listen addresses, and TLS status.
Inputs: no named parameters.
caddy_stopADestructive
Gracefully shut down the Caddy server. Requires confirm=true to prevent accidental shutdown.
Inputs: confirm (required).
caddy_tlsAIdempotent
Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL, 'set_acme_profile' sets the ACME profile (Caddy 2.10+), 'ech_status' reads the Encrypted ClientHello config at apps/tls/encrypted_client_hello (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances, including one with no config at all: the set_* actions create apps/tls, and any missing parents, when it is not set. Writes target policies[0].issuers[0] only, and only when that issuer's module is 'acme' -- on a multi-policy TLS config, or one whose first issuer is 'internal' (Caddy's local CA), edit the intended issuer with caddy_config_set instead.
Inputs: action (required), ca, email, profile.
caddy_upstreamsARead-onlyIdempotent
Caddy's /reverse_proxy/upstreams array (address, num_requests, fails), returned verbatim. On Caddy 2.11.2+ it is not the configured upstream list. Dynamic-upstream backends stay listed about 1 h (up to ~65 min) after the dynamic source last returned them, even after a config change removes them, so an address may appear that no current config references. A backend with requests in flight can appear twice when its resolved address differs from the entry's text (dynamic upstreams, tcp/ or unix// dials, placeholder dials). That extra copy always shows fails 0 and repeats num_requests, so do not sum num_requests across entries.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Multiple tools can write config (caddy_config_set, caddy_config_by_id, caddy_load, caddy_add_route, caddy_reverse_proxy), and delete overlaps similarly (caddy_config_delete vs caddy_remove_route), so boundaries are not perfectly clean. However, the descriptions go to great lengths to explain when each applies (low-level path vs @id vs convenience wrapper), making selection tractable for an agent.
Every tool carries the caddy_ prefix in consistent snake_case, forming recognizable families (config_get/set/delete, list_servers/routes, add_route/remove_route). Minor deviation: several tools are bare nouns (caddy_status, caddy_metrics, caddy_upstreams, caddy_pki) rather than verb_noun, but the overall pattern is predictable.
18 tools is on the heavier side but each earns a place, spanning config CRUD, route helpers, snapshots, TLS/PKI, metrics, and lifecycle. Slightly over what a minimal config server would need, but well-scoped for Caddy's breadth.
The surface covers the full config lifecycle (read, write, delete, whole-config load, snapshot/revert), route management, TLS/PKI configuration, observability (metrics, upstreams), format adaptation, and graceful shutdown. No obvious dead ends for administering Caddy via its admin API.
Maintenance
Related MCP Connectors
Lets your AI build and edit websites in Xodia, a visual website builder for real code (Vite, React, Tailwind CSS or plain HTML in your own git repo): read and write site files, create pages and CMS collections, run typecheck, design and link checks, take screenshots, manage forms and translations, and pick up change requests the user sends from the visual editor. Sign in once with your Xodia account (OAuth). Free plan, no card needed. Setup: https://xodia.ai/ai/mcp
Zero-dependency Cloudflare Worker gateway turning websites and REST APIs into MCP tools.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables inspection and management of Caddy reverse proxy configuration via CaddyUI's REST API, including proxy hosts, redirection hosts, raw routes, and TLS certificates.3MIT
- AlicenseAqualityBmaintenanceMCP server for Cognigy.AI - 132 tools that let Claude, Cursor & other AI assistants build, configure, test & operate conversational AI agents via the Model Context Protocol.13836 npm2MIT
- AlicenseAqualityCmaintenanceMCP server for safely inspecting and operating a local Caddy admin API. Provides read-only tools and dry-run mutations for config management.7MIT
- AlicenseAqualityDmaintenanceEnables management of Caddy web server via admin API, allowing inspection of routes, upstream health, certificates, and configuration reloading.16MIT