Claude Code、Cursor、および任意の MCP クライアントから Caddy Web サーバーを管理します。 Caddy の管理 API のすべてのエンドポイント（設定、ルート、リバースプロキシ、TLS、PKI、メトリクス、スナップショット）をカバーする 18 のツール + 4 のリソース。
Yaw Labs によって構築・保守されています。
ワンクリックでこれをローカルの Yaw MCP 設定に追加し、すべての Yaw Terminal セッションで利用できるようにします。または、下記から手動でインストールします。
他の Caddy MCP サーバーは管理 API の半分しかラップしておらず、エラーを黙って飲み込みます。これはそうではありません。
完全な管理 API カバレッジ — 文書化されたすべてのエンドポイント: /load、/config/*、/id/*、/stop、/adapt、/pki/ca/*、/reverse_proxy/upstreams、/metrics。404 を返すプレースホルダーツールはありません。
安全な並行書き込み — ETag（If-Match）を使用するため、自分の変更が他人の変更を黙って上書きすることはありません。HTTP 412 Precondition Failed を難解なエラーではなく明確なメッセージとして表示します。
デフォルトで安全な変更 — caddy_config_set はデフォルトで冪等な overwrite（PATCH）を使用し、append（POST）ではありません。2 回呼び出してもルートが重複しません。
防御的なパース — caddy_list_routes は、routes が null でも、handlers が文字列でも、matchers が配列でなくても、不正な設定でクラッシュしません。リグレッションテスト済みです。
エラーに資格情報を漏らさない — CADDY_ADMIN_URL のパス/クエリにトークンが含まれている場合、接続失敗メッセージにはオリジンのみが表示されます。
フォールバックエラーの表示 — TLS 書き込み PATCH が失敗し、POST フォールバックも失敗した場合、両方のエラーボディが返されるため、実際に何が問題だったのかがわかります。
ツールアノテーション — すべてのツールが readOnlyHint、destructiveHint、idempotentHint を宣言するため、MCP クライアントは安全な操作の確認をスキップできます。
即時起動 — 2 つのランタイム依存関係（MCP SDK + Zod）を持つ単一バンドルとして提供されます。5 分かかる node_modules のインストールは不要です。
入力の堅牢化 — アダプター名、@id 値、サーバー名、CA ID はすべて正規表現で検証され、長さの上限があります。CRLF ヘッダーインジェクションと ReDoS をブロックします。
Related MCP server: InfraOps MCP Server
1. Caddy 管理 API を有効にする
Caddy はデフォルトで localhost:2019 で管理 API が有効な状態で提供されます。Docker やリモートホストで Caddy を実行している場合は、CADDY_ADMIN_URL 経由で公開してください。
2. プロジェクトルートに .mcp.json を作成する
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"]
}
}
}なぜ Windows では追加の手順が必要なのか？ Node 20 以降、
child_process.spawnは.cmdファイルを直接実行できません（Windows ではnpxがそれに該当します）。cmd /cでラップするのが標準的な回避策です。このファイルはコミットしても安全です — 秘密情報は含まれていません。
3. 再起動して承認する
Claude Code（または MCP クライアント）を再起動し、プロンプトが表示されたら Caddy MCP サーバーを承認します。
これで完了です。あとは AI アシスタントに次のように依頼します:
"api.local を localhost:3000 にプロキシして"
"srv0 にはどのルートが設定されていますか？"
"Prometheus メトリクスを表示して"
環境変数 | デフォルト | 説明 |
|
| Caddy 管理 API の URL。Docker 内では |
| (none) | 認証付き管理エンドポイント用のオプションの Bearer トークン。Caddy に認証を設定している場合にのみ必要です。 |
| (none) |
|
|
| 一時的な障害（5xx、ネットワークエラー）に対する再試行回数。4xx と 412 は再試行しません。 |
|
|
|
|
|
|
Unix ソケット管理エンドポイント:
Caddy が推奨する堅牢化は、管理 API をループバックポートから unix ソケットに移すことです。unix ソケットではアクセスがファイルシステムの権限によって制御されます:
{
admin unix//var/run/caddy-admin.sock
}CADDY_ADMIN_URL を同じパス（unix:///var/run/caddy-admin.sock）に指定すると、リクエストは TCP ではなくソケット経由で送信されます。caddy-mcp を実行するプロセスには、ソケットファイルの読み取り/書き込み権限が必要です。エンドポイントの前に認証を設定している場合は、CADDY_API_TOKEN が引き続き適用されます。
その他の MCP クライアント:
クライアント | 設定ファイル |
Claude Code |
|
Claude Desktop |
|
Cursor |
|
Windsurf |
|
VS Code |
|
上記と同じ JSON ブロックをこれらのいずれでも使用できます。
caddy_config_get — 任意の JSON パス（または完全な設定）で設定を読み取ります。
caddy_config_set — パスに設定を書き込みます。モード: overwrite（PATCH、デフォルト、冪等）、append（POST）、insert（PUT、配列の位置指定用）。
caddy_config_delete — パスの設定を削除します。confirm=true が必要です（親パスを削除すると、すべての子孫も削除されます）。
caddy_config_by_id — @id タグで設定を取得/設定/削除します — 深いパスをたどるよりはるかに簡単です。delete アクションには confirm=true が必要です。
caddy_load — 設定全体をアトミックに置き換えます。証明書プロビジョニングのタイムアウトは 60 秒。以前の設定を自動的にスナップショットします。
caddy_revert — ロールバック用の設定スナップショットを管理します。アクション: list、save、apply（確認ゲート付き）。メモリ内に最新 10 件。
caddy_reverse_proxy — 1 回の呼び出しでリバースプロキシを追加します: from='api.local' to=['localhost:3000']。冪等な書き込みのためにオプションの id を渡すと、繰り返し呼び出してもルートが重複せず、その場で置き換えられます。
caddy_add_route — 完全な match/handle 制御（任意の Caddy ハンドラー）でルートを追加します。
caddy_remove_route — @id（推奨）またはインデックスでルートを削除します。confirm=true が必要です。
caddy_list_routes — 人間が読めるルートの概要。防御的: 奇妙な設定でもクラッシュしません。
caddy_tls — TLS 設定を確認または設定します: ACME メール、ACME CA URL。まず PATCH を試み、新規インストールの場合は最小限の設定を POST します。既存の設定がある場合は issuer パスにディープマージし、結果を PUT して戻します。兄弟要素（カスタム証明書、on_demand、追加ポリシー）は保持されます。既存の構造が想定外の場合は、形状固有のエラーで拒否します — 決して上書きしません。
caddy_adapt — 登録済みの任意のアダプター形式の設定を、適用せずに Caddy JSON に変換します。caddyfile（組み込み、デフォルト）に加えて、Caddy バイナリにコンパイルされた任意のアダプターモジュール — 例: nginx（caddy-nginx-adapter）、yaml（caddy-yaml）。既存の設定のプレビューや移行に最適です。
caddy_status — 接続確認 + 設定サマリー（サーバー数、ルート、TLS モード）。
caddy_list_servers — 名前、アドレス、ルート数、TLS ステータスを含むすべての HTTP サーバーを一覧表示します。
caddy_upstreams — リバースプロキシのバックエンドのヘルス状態。
caddy_metrics — Prometheus メトリクス（リクエスト数、所要時間、接続数、TLS ハンドシェイク）。オプションの filter（メトリクス名の部分一致、保持されるメトリクスの # HELP / # TYPE 行も保持）と max_lines（デフォルト 500）により、混雑したサーバーでもレスポンスをコンパクトに保ちます。
caddy_pki — CA 情報と証明書チェーン（デフォルト CA: local）。
caddy_stop — グレースフルシャットダウン。事故を防ぐために confirm=true が必要です。
閲覧可能な読み取り専用データ — MCP クライアントはツール呼び出しなしでこれらを直接取得できます:
caddy://config — 現在の完全な Caddy JSON 設定。
caddy://servers — 設定されているすべての HTTP サーバーのサマリー。
caddy://upstreams — リバースプロキシのアップストリームのヘルスステータス。
caddy://metrics — Prometheus メトリクス（テキスト表記形式）。クライアントのコンテキストを制限するため、最初の 500 行に制限されています。フィルタリングやより大きな出力には、filter / max_lines を指定した caddy_metrics ツールを使用してください。
> "Proxy api.example.com to my app on port 3000"
→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"] })> "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.> "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.> "Convert this Caddyfile to JSON so I can review it:
example.com {
reverse_proxy localhost:8080
}"
→ caddy_adapt({ config: "..." })> "Fetch Prometheus metrics and tell me which route is slowest"
→ caddy_metrics()> "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 first> "Replace the whole config with this Caddyfile"
→ caddy_adapt({ config: "..." }) # validate first
→ caddy_load({ config: adaptedJson }) # apply atomically"Caddy admin API に接続できません"
Caddy が実行されていることを確認してください。caddy run または systemctl status caddy。
admin エンドポイントを確認してください。デフォルトは http://localhost:2019 です。Caddy が Docker 内にある場合は、コンテナのホスト名を使用してください。
一致するように、MCP 設定の env に CADDY_ADMIN_URL を設定してください。
"HTTP 412 Precondition Failed"
読み取りと書き込みの間に、誰か（または何か）が設定を変更しました。
キャッシュされた ETag が無効になっています。設定を読み直して、再試行してください。
"HTTP 403"（/load または /config への書き込み時）
Caddy 設定で admin.listen または admin.origins の制限を設定しているか、Authorization ヘッダーが不足しています。
Caddy が Bearer トークンを期待する場合は、MCP 設定の env に CADDY_API_TOKEN を設定してください。
SIGUSR1 / systemctl reload caddy が Caddyfile のリロードを停止する
これは想定された動作であり、ここでのバグによるものではありません。Caddy 2.11.1 以降、SIGUSR1 は、
ディスク上のファイルから、設定が admin API を通じて一度も変更されたことがない
場合にのみリロードします。caddy-mcp（または他の API クライアント）による最初の書き込みにより、
Caddy は実行中の設定が API によって所有されているとみなすようになり、SIGUSR1 は no-op になります。
インスタンスごとに 1 つの所有者を選んでください。Caddyfile が信頼できる情報源である場合は、
caddy-mcp の読み取り専用ツール（caddy_status、caddy_list_routes、caddy_adapt）を使用し、
ファイルからリロードしてください。caddy-mcp が設定を所有する場合は、
SIGUSR1 の代わりに caddy_load で変更を適用してください。
Windows: MCP サーバーが起動しない
クイックスタートセクションの cmd /c npx ... パターンを使用してください。Node 20+ は .cmd ファイルを直接起動できません。
Node.js 20+
admin API が有効な Caddy 2.x（デフォルト: localhost:2019）。Caddy 2.11.4 で検証済み。
@id 書き込みパスは、ライブ統合スイートがリリースごとに固定する PATCH セマンティクスに
依存しています。
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 (357 unit tests, +9 POSIX-only unix-socket tests; +13 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
npm run typecheck # tsc --noEmitCONTRIBUTING.md に、リリースプロセスを含む完全なワークフローが記載されています。
MIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
| config | Yes | The raw config text (e.g., Caddyfile contents, nginx.conf, yaml) | |
| adapter | No | Config format adapter. Must match an adapter Caddy was built with. Built-in: 'caddyfile' (default). Common external adapters: 'nginx' (caddy-nginx-adapter), 'yaml' (caddy-yaml). | caddyfile |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral context: conversion is done locally ('without loading it'), returns 'adapted JSON and any warnings separately', and requires adapter modules to be compiled in. This exceeds annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main verb 'Convert', with each sentence providing necessary detail (purpose, usage, output). No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers purpose, usage, prerequisites, and return format. It is self-contained for an agent to decide when to invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. The description enriches by listing built-in ('caddyfile') and external adapters ('nginx', 'yaml') and noting adapter module requirements, which adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Convert a config in any registered adapter format to Caddy JSON without loading it.' This clearly identifies the action (convert), the resource (config), and the output (Caddy JSON). The 'without loading it' distinguishes it from loading-related siblings like caddy_load.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs.' This gives explicit use cases. However, it does not explicitly name sibling alternatives or state when not to use, so it provides clear context but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.).
| Name | Required | Description | Default |
|---|---|---|---|
| match | Yes | Array of match objects (e.g., [{ host: ['example.com'], path: ['/api/*'] }]) | |
| handle | Yes | Array of handler objects (e.g., [{ handler: 'file_server', root: '/var/www' }]) | |
| server | No | Caddy server name (default: srv0) | srv0 |
| terminal | No | Stop processing further routes after this one matches |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, providing minimal safety context (not read-only, not idempotent, not destructive). The description adds capability details (supports any handler) but does not disclose behavioral traits such as whether the route is appended or overwrites existing routes, validation behavior, or reversibility. This is a moderate gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and contains no fluff. Every word adds relevant context about what the tool does and its flexibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage and absence of an output schema, the description covers the tool's purpose and scope effectively. It misses some behavioral context (e.g., route ordering, interaction with terminal flag) but is reasonably complete for a config-modifying tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by enumerating common handler types (reverse_proxy, file_server, etc.) and emphasizing 'full control', which helps the agent understand the flexible, free-form nature of the match and handle parameters beyond the schema's minimal examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Add a route') and its scope ('full control over match conditions and handlers'). It also lists specific handler types, which distinguishes it from sibling tools like caddy_remove_route and caddy_list_routes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'full control' implies this is the general-purpose tool for adding routes, and mentioning 'any Caddy handler' suggests flexibility. However, it does not explicitly state when to use this versus alternatives like caddy_reverse_proxy, nor does it provide any exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The @id value of the config object | |
| mode | No | For 'set' action: 'overwrite' = PATCH (replace existing, default), 'append' = POST (add to arrays, create on objects), 'insert' = PUT (insert at array index) | overwrite |
| value | No | New value (required for 'set' action) | |
| action | No | Action to perform | get |
| confirm | No | Must be true to actually delete (only enforced for action='delete') | |
| subpath | No | Optional sub-path within the identified object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveness (destructiveHint=true, readOnlyHint=false), so the bar is lower. The description adds concrete safety behavior beyond the annotations: 'The delete action requires confirm=true,' and it clarifies the tool is multi-modal (read/update/delete), which nuances the blanket destructive hint by showing only one of three actions is destructive. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the mechanism, the scope of operations, and the one safety caveat that must not be missed (confirm=true). The key concept (addressing by @id) is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter tool with no output schema, the description covers the conceptual model (what @id is), the available actions, and the delete safeguard, while the 100%-coverage schema handles all parameter detail. The only gaps are response shape and error behavior for unknown @ids, which are secondary for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the mode enum already documenting PATCH/POST/PUT semantics, so the baseline is 3. The description adds useful conceptual context for the id parameter — that any config object carrying an '@id' field is addressable — but it adds nothing about value, subpath, action, or confirm beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific mechanism and resource ('Access config by @id tag') and expands to enumerate the three operations ('read, updated, or deleted') and the addressing advantage ('instead of needing its full path'). This substantively distinguishes the tool from the path-based caddy_config_get/set/delete siblings by its unique addressing model, even though it never names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'This is the recommended way to manage individual routes and config objects' gives an explicit positive recommendation for when to use the tool, and 'instead of needing its full path' implies the alternative of path-based config access. However, it names no sibling tool explicitly and gives no exclusion criteria, leaving the boundary against caddy_add_route/remove_route implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Config path to delete (e.g., 'apps/http/servers/srv0/routes/0') | |
| confirm | No | Must be true to actually delete the config node (safety) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as destructive and not read-only. The description usefully adds that deleting a parent node cascades to all descendants and provides a concrete example, plus the confirm=true safety guard. This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words: the core action is first, then the critical cascade behavior with an example, then the required confirmation flag. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation, the description covers the target path, the example, cascade semantics, and the safety gate. It omits details like behavior for nonexistent paths or response/error values, but annotations and schema already cover the key safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and both parameters already have descriptive documentation in the schema. The description repeats the confirm requirement and gives an example path, adding little new meaning about the parameters themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete config at a JSON path') and the resource (Caddy config), with a precise definition of deleting a node and its descendants. It does not explicitly differentiate from sibling tools like caddy_remove_route, but the JSON-path framing makes the scope reasonably distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool over alternatives such as caddy_config_set or caddy_remove_route. The confirm=true requirement is a safety parameter, not a usage-or-alternative guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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').
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Config path (e.g., 'apps/http/servers/srv0') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context by explaining the return behavior for empty vs. specific paths, which goes beyond the structured annotations and helps the agent predict the tool's output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every word adds value. It avoids needless detail while including a practical example. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description covers the essential behaviors: full config vs. subtree, path example, and empty path default. It doesn't mention error handling or exact output format, but these are relatively minor gaps given the tool's simplicity and strong annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the only parameter 'path', but the description enriches its meaning by explicitly stating that an empty path returns the full config and providing a concrete example ('apps/http/servers/srv0/routes'). This goes beyond the schema's generic 'Config path' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads Caddy config at a JSON path, with a specific verb ('Read') and resource. It distinguishes itself from siblings by being the generic config getter, while other tools handle writes, deletes, or specific lookups. The clarification of empty path returning the full config adds scope precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied: use this to read config by path. However, there is no explicit guidance on when to prefer this tool over alternatives like caddy_config_by_id or caddy_status, nor any exclusions. The description provides clear context but no comparative direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write config at a JSON path. Mode 'overwrite' (default) replaces existing values (PATCH) — safe and idempotent. Mode 'append' adds to arrays or creates keys (POST) — NOT idempotent: calling twice with the same route duplicates it. Mode 'insert' places at a specific array index (PUT) — useful for route ordering.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'overwrite' = PATCH (replace existing, default, idempotent), 'append' = POST (add to arrays / create keys, NOT idempotent), 'insert' = PUT (insert at array index) | overwrite |
| path | Yes | Config path to write to (e.g., 'apps/http/servers/srv0/routes') | |
| value | Yes | The JSON value to set at the path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the sparse annotations by detailing HTTP semantics (PATCH/POST/PUT), idempotency per mode, and side effects like route duplication on repeated 'append' calls. It also highlights the 'insert' mode's utility for ordering. This fully discloses behavioral traits and potential pitfalls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (two sentences) and front-loaded with the core purpose before detailing modes. Each mode is explained with relevant consequences, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's behavior comprehensively: modes, idempotency, side effects, and ordering use-case. It doesn't mention return values, but the absence of an output schema makes that less critical. Given the complexity of the tool (three modes with different behaviors), this description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already well-documented. The description adds value by explaining the mode-specific behaviors (idempotency, side effects) that the schema enum descriptions only hint at. It does not add much for 'path' or 'value', but the schema already provides examples and definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Write config at a JSON path.' It specifies the resource (config), the action (write), and the path-based scope. This distinguishes it from sibling tools like caddy_config_get or caddy_config_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use each mode: 'overwrite' for safe/idempotent replacement, 'append' for adding to arrays (with warning about duplication), and 'insert' for route ordering. It doesn't explicitly mention alternatives to the tool itself, but the mode guidance is strong and context-rich.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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'.
| Name | Required | Description | Default |
|---|---|---|---|
| server | No | Caddy server name (default: srv0) | srv0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds significant behavioral detail: output caps (500 routes/20000 chars), whole-route truncation, omission note, and exact fallback path. This fully discloses edge-case behavior without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences that each add distinct value: purpose/output, caps/truncation, and fallback. No redundant filler; structure is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with one optional parameter and no output schema, the description covers output format, limits, edge-case behavior, and how to get the complete data. It is fully self-contained for an agent to invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'server' is already documented in the schema with default 'srv0' and 100% coverage. The description does not add additional parameter-level detail but doesn't need to given the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists all routes on a Caddy HTTP server and describes the dual output (summary + raw JSON). The use of 'all routes' and explicit reference to caddy_config_get for reading the rest distinguishes it from sibling config-read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when you want a quick route overview on a specific server, and explicitly directs to caddy_config_get at a specific JSON path for the full untruncated data. The cap behavior and omission note also tell the agent when the result is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, read-only, idempotent operation. The description adds transparency about the output content (specific server attributes), which is helpful given there is no output schema. This goes beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action and output details, followed by a practical usage hint. Every sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list operation with strong annotations, this description is complete. It tells the agent exactly what the tool does, what it returns, and when to invoke it, making tool selection and usage straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is fully covered by default. Per the baseline for 0-parameter tools, the description appropriately focuses on behavior and output rather than parameter explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation as listing all configured HTTP servers and specifies the exact data returned (names, listen addresses, route counts, TLS status). This distinguishes it from sibling tools like caddy_list_routes, which focus on routes rather than servers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this to discover server names before calling route tools.' This provides a clear workflow context, though it does not explicitly name alternatives or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Has a 60-second timeout to allow for TLS provisioning. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| config | Yes | Full config — JSON object or Caddyfile text string | |
| format | No | Config format: 'json' (default) or 'caddyfile' | json |
| confirm | No | Must be true to replace the running configuration (safety) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations already declaring destructiveHint and idempotentHint, the description adds significant behavioral detail: atomicity, a 60-second timeout for TLS provisioning, the mandatory confirm=true requirement, the fact that the entire running config is discarded, and that a snapshot is taken allowing restore via caddy_revert. These details greatly exceed what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, with the primary action front-loaded in the first sentence. Every sentence carries substantive information: format options, safety/timeout, destructive consequences, and snapshot/restore. There is no filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, high-stakes operation, the description provides comprehensive guidance: it warns about the full config discard, mandates confirm=true, mentions atomicity and the timeout, and explains the snapshot/revert path. It also positions itself relative to large config changes. The absence of an output schema is not a meaningful gap since the return value is secondary to the behavioral warnings covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage by describing all three parameters, but the description adds complementary meaning: it clarifies that config can be a JSON object or a Caddyfile string, ties format='caddyfile' to that choice, and explains that confirm=true is required because the action discards the entire running config. This adds context beyond the schema, though it does not individually explain every parameter in depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Replace the entire Caddy configuration atomically,' using a specific verb ('replace') and a clear resource ('entire Caddy configuration') with a distinctive behavior ('atomically'). This distinguishes it from sibling tools like caddy_config_set or caddy_config_delete, which likely target partial changes. The mention of accepting JSON or Caddyfile further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'This is the safest way to make large config changes,' providing clear context for when to use this tool. It also mentions restoration via caddy_revert, giving an alternative fallback. However, it does not explicitly say when not to use it (e.g., for small targeted changes) or name alternative tools like caddy_config_set, so it stops short of a full when/when-not distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Substring to match against metric names. Keeps sample lines whose metric name contains this substring, plus their `# HELP` and `# TYPE` comment lines. Empty/absent = no filtering. Label values are NOT matched -- use a Prometheus-aware client for label filtering. | |
| max_lines | No | Maximum number of output lines (default 500). Excess lines are dropped and a summary is appended. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: output can be megabytes, filter-mode drops blank/free-form comments but preserves HELP/TYPE lines, '# EOF' is always kept, max_lines defaults to 500, and a trailing comment reports dropped lines. This goes well beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized—four sentences that lead with the core purpose, then dive into parameter behavior with examples. Every sentence carries unique, essential information; there is no repetition or filler. The structure flows logically from purpose to usage to edge cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the return format implicitly (Prometheus text) and explicitly covers filtering semantics, line handling, size limits, and the trailing summary. It gives the agent enough context to anticipate output characteristics and pitfalls, making it complete for invocation and result handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description significantly enriches parameter meaning. It explains that filter is a substring match on metric names, that HELP/TYPE lines for matching metrics are retained, and that label values are NOT matched. For max_lines, it details the default (500) and the appended summary line, which the schema does not fully convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get Prometheus metrics from Caddy.' It lists concrete metric categories (request counts, durations, TLS handshake stats, active connections) and clearly distinguishes this tool from sibling tools like caddy_config_get or caddy_status, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the filter and max_lines parameters, including examples and edge-case behavior (label values not matched). It does not explicitly contrast with alternatives, but among the siblings none offer metrics, so the context is clear enough for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get PKI certificate authority info or the CA certificate chain.
| Name | Required | Description | Default |
|---|---|---|---|
| ca | No | CA ID (default: 'local') | local |
| certificates | No | If true, return the full CA certificate chain |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds little beyond repeating the certificates parameter's effect, and does not disclose additional behavioral traits such as output format or error behavior. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that begins with the verb and directly states the tool's purpose. No filler or redundant information, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only getter with no output schema, yet the description is vague about what 'info' includes or what the response format looks like. While annotations and schema cover parameters and safety, the description lacks contextual detail about the return value or edge cases, making it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% (both 'ca' and 'certificates' have descriptions). The description does not add any additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with the verb 'Get' and clearly identifies the resource as 'PKI certificate authority info or the CA certificate chain.' This is specific and distinguishes it from siblings like caddy_config_get or caddy_status, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage as a read-only query for PKI CA information, but does not explicitly state when to use it over alternatives like caddy_tls or caddy_config_get. No exclusions or alternative tool references are provided, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The @id of the route to remove (preferred — stable even if routes get reordered) | |
| index | No | Zero-based index of the route in the server's routes array (only used if id is not provided) | |
| server | No | Caddy server name when using index (default: srv0). Ignored when id is provided. | srv0 |
| confirm | No | Must be true to actually remove the route (safety) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by clarifying that idempotency is mode-dependent: @id mode is idempotent, while index mode is not and can remove different routes on repeated calls. It also discloses the two-step read-then-delete race, the config-global scope of @ids, and the refusal behavior when the id resolves to a non-route object. This is excellent behavioral disclosure for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries essential operational or safety information. The description is front-loaded with the core action, then systematically covers target selection, idempotency differences, concurrency hazards, and scope semantics. There is no filler or repetition that does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent tool with no output schema, the description is remarkably complete. It addresses the main failure modes (race conditions, repeated index removal, non-route @id targets), explains the confirm-based safety mechanism indirectly through the schema, and gives the agent enough context to call the tool correctly and avoid destructive mistakes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains why id is preferred, warns that index removal re-packs the routes array, and clarifies that @ids are config-global rather than route-scoped. This enriches the agent's understanding of how id and index actually behave.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a direct, specific statement—'Remove a route'—and immediately identifies the two targeting modes (@id or index on a specific server). This clearly distinguishes it from generic config deletion tools and from route-modification siblings like caddy_add_route or caddy_list_routes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: prefer @id because it is stable across reorderings, avoid index mode when possible because it can race against concurrent edits. It does not explicitly compare this tool to alternatives like caddy_config_delete, but the contextual guidance for choosing between the tool's own modes is strong and concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Optional stable @id for the route. When set, repeat calls REPLACE the route in place (idempotent). When omitted, the route is APPENDED — calling twice with identical args creates a duplicate route. @ids are config-global in Caddy: if this id is already used by a non-route object the call refuses rather than clobbering it. | |
| to | Yes | Upstream addresses, at least one (e.g., ['localhost:3000', 'localhost:3001']). An 'https://' prefix dials the upstream over TLS (port 443 unless one is given); http:// and bare addresses are dialed in the clear. Do not mix https:// and non-https entries in one call. | |
| from | Yes | Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws') | |
| server | No | Caddy server name (default: srv0) | srv0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses conditional idempotency (append vs PATCH replace), config-global @id semantics, collision refusal, behavior after an id is registered, and TLS transport rules. This goes well beyond the coarse annotations and is not contradicted by them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but well organized: the one-line purpose and example come first, followed by idempotency, id-scoping behavior, and upstream handling. Every sentence carries operational information; there is no filler or repetition beyond what is safety-relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a config-mutating tool with four parameters and no output schema, this description covers all calling modes, failure modes (collision refusal, mixed-scheme refusal), and side effects (in-place replacement, global id behavior). An agent has enough information to call it correctly and predict repeat-call behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning beyond the schema: id omission vs supply changes idempotency, upstream scheme changes transport and default port, and mixed scheme lists are refused. The example also makes the from/to shape concrete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Add a reverse proxy route') and gives a concrete from/to example, making the operation unmistakable. The domain-specific phrasing also separates it from the generic sibling caddy_add_route, and the final note references caddy_add_route as the lower-level fallback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends supplying a stable id for automation, warns that omitting id duplicates routes, and gives a clear alternative (caddy_add_route) for mixed https/non-https upstreams. This gives an agent concrete decision rules rather than leaving tool selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load (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).
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Snapshot index for 'apply' (0 = most recent, default) | |
| action | Yes | Action to perform | |
| confirm | No | Must be true to actually apply a snapshot (safety) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description aligns by noting 'apply' restores a snapshot and requires confirm=true. It adds valuable context beyond annotations: snapshots are auto-captured before caddy_load, are kept to the last 10, and are lost on server restarts unless a directory is configured. This discloses persistence and destructive implications that annotations alone do not convey. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and each clause earns its place. It packs a lot of information—auto-capture, retention, persistence caveat, and actions—without bloat. The structure is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and no output schema, the description covers the essential behavior: what actions exist, persistence, and the safety requirement for apply. It doesn't describe return types (not required without output schema) or error handling, but those are minor. It could go further by explicitly stating that 'apply' overwrites the active config, but that is strongly implied by 'restores a snapshot'. Overall it is sufficiently complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is documented in the schema. The description nevertheless adds semantic value by explaining the meaning of each action value ('list' shows snapshots, 'save' captures, 'apply' restores), and reinforcing that confirm must be true for apply. While the schema already describes index as '0 = most recent', the description's action semantics help the agent understand the workflow without opening an enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages config snapshots for rollback, and enumerates three specific actions (list, save, apply). This distinguishes it from sibling tools like caddy_load or caddy_config_set, which deal with live config rather than snapshots. The verb 'manage' plus the resource 'config snapshots' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for snapshot operations) and includes a critical caveat about snapshots being memory-only and lost on restart unless CADDY_MCP_SNAPSHOT_DIR is set. It also notes that 'apply' requires confirm=true, which is a usage requirement. However, it does not explicitly contrast with alternatives like caddy_load or caddy_config_set, leaving some routing to inference. The context is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check Caddy connectivity and get a config summary: servers, routes, listen addresses, and TLS status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is clear. The description adds valuable context about what the summary contains (servers, routes, listen addresses, TLS status), going beyond the annotations. It does not discuss failure modes, but the annotation coverage lowers the bar and the added context is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that packs significant information: the verb ('Check'), the resource ('Caddy connectivity'), and a detailed summary content list. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is complete. It explains both the action (connectivity check) and the expected return content (config summary with servers, routes, listen addresses, TLS status). Rich annotations further cover the safety profile, so the description sufficiently covers all necessary contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema is trivially complete (coverage 100%). Per guidelines, 0 params receives a baseline score of 4 because there are no parameter gaps to address. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Check Caddy connectivity and get a config summary'. It also enumerates the summary content (servers, routes, listen addresses, TLS status), which distinguishes it from sibling tools like caddy_config_get (full config) and caddy_list_servers (specific server list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the tool provides connectivity checks and a config summary, but it does not explicitly recommend it over alternatives or mention when not to use it. It provides clear context for when this tool is appropriate, but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gracefully shut down the Caddy server. Requires confirm=true to prevent accidental shutdown.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to confirm shutdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds meaningful context by specifying 'gracefully' shutdown and the confirm=true safeguard, which helps the agent understand the manner and safety requirement of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action, and every word contributes value. There is no filler or redundant elaboration beyond the necessary confirmation note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter stop operation with clear annotations and full schema coverage, the description is sufficient. It does not explain return values or edge cases, but given the low complexity and existing structured data, that is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the confirm parameter with 100% coverage ('Must be true to confirm shutdown'). The description only repeats this requirement without adding new semantic detail, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'shut down' with a clear resource 'Caddy server', and it is distinct from sibling tools that handle config, status, or routes. The action and target are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use (to stop the server) but does not explicitly state when to use it versus alternatives or when not to use it. The confirm requirement is a prerequisite, not a usage guideline. It lacks explicit context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| ca | No | ACME CA URL (for 'set_acme_ca' action) | |
| No | ACME email address (for 'set_email' action) | ||
| action | Yes | Action to perform | |
| profile | No | ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds substantial behavioral context: write scope is restricted to policies[0].issuers[0], writes only occur when the issuer module is 'acme', 'ech_status' is read-only, and profile validity is CA-defined. This fully discloses side effects and limitations beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: actions are front-loaded, followed by compatibility notes, write-scope constraints, and a concrete routing instruction to a sibling tool. No filler or restatement of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of five actions with different constraints, the description fully covers behavior, version requirements, write targets, and fallback routing to caddy_config_set. The absence of an output schema is mitigated by the clear action-level descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters, but the description adds meaning beyond it: the profile parameter's version requirement, CA-defined valid values, and the Let's Encrypt 'shortlived' example. This enriches the agent's understanding without redundant repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a clear verb-resource pairing ('Get or configure TLS/HTTPS settings') and enumerates every supported action with specific targets (ACME email, CA URL, profile, ECH status). It distinguishes itself from caddy_config_set by naming the exact condition under which that sibling should be used instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: it works on fresh or existing instances, but for multi-policy TLS configs or non-ACME first issuers it directs the agent to use caddy_config_set. It also flags version-dependent actions (Caddy 2.10+), leaving no ambiguity about applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond annotations by explicitly listing the output fields (address, active requests, failure counts), which is the primary behavioral detail for a status tool. It does not contradict annotations and provides useful context about what the agent will receive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately stating the action and resource, then enumerating the returned data. Every word is functional with no filler or repetition. It is front-loaded with 'Get the current health status' and remains compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 params, no output schema, strong annotations), the description covers the essential aspects: what it does and what it returns. It lists the three key fields, which is sufficient for an agent to understand the tool's output. However, it does not specify the exact response format or how health status is determined, leaving minor ambiguity for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with 0 parameters, so the baseline is 4. The description correctly makes no mention of parameters, as none exist. It neither adds nor needs to add parameter semantics since there is nothing to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific function: getting current health status of reverse proxy upstreams. It lists the exact data shown (address, active requests, failure counts), distinguishing it from sibling tools like caddy_status (overall Caddy status) and caddy_reverse_proxy (likely configuration). The verb 'Get' plus the specific resource makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need upstream health information) but provides no explicit guidance on alternative tools or exclusions. It does not mention when not to use it or how it compares to caddy_status or caddy_metrics, leaving the agent to infer usage context from the purpose statement alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.4.0caddy_reverse_proxy3 fields changedInput schema / properties / to / descriptionPrevious value: -"Upstream addresses (e.g., ['localhost:3000', 'localhost:3001'])"New value: +"Upstream addresses, at least one (e.g., ['localhost:3000', 'localhost:3001']). An 'https://' prefix dials the upstream over TLS (port 443 unless one is given); http:// and bare addresses are dialed in the clear. Do not mix https:// and non-https entries in one call."Input schema / properties / to / items / minLengthAdded value: +1Input schema / properties / to / minItemsAdded value: +1v2.3.2caddy_tls2 fields changedInput schema / properties / action / enumPrevious value: -[
- "status",
- "set_email",
- "set_acme_ca"
-]New value: +[
+ "status",
+ "set_email",
+ "set_acme_ca",
+ "set_acme_profile",
+ "ech_status"
+]Input schema / properties / profileAdded value: +{
+ "description": "ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy.",
+ "type": "string"
+}v2.2.0caddy_adaptcaddy_add_routecaddy_config_by_idcaddy_config_deletecaddy_config_getcaddy_config_setcaddy_list_routescaddy_list_serverscaddy_loadcaddy_metricscaddy_pkicaddy_remove_routecaddy_reverse_proxycaddy_revertcaddy_statuscaddy_stopcaddy_tlscaddy_upstreamsMost tools target a distinct Caddy resource or operation, and the detailed descriptions clarify the intended use. The main sources of ambiguity are caddy_config_by_id overlapping with config_get/set/delete and caddy_reverse_proxy overlapping with caddy_add_route, but those are understandable with careful reading.
All tool names share the caddy_ prefix, which provides some cohesion, but the internal pattern is mixed: config_get/config_set/config_delete use object-first naming, add_route/list_routes/remove_route use verb-first naming, and tls/status/upstreams/pki/metrics are bare nouns. This is readable but not a single predictable convention.
At 18 tools this is slightly over the typical well-scoped range, but the Caddy domain is broad and most tools serve a distinct need across config, routes, TLS, monitoring, and lifecycle. The count feels justified rather than bloated, though a few status/metrics tools could arguably be consolidated.
The toolset covers generic config CRUD, full config load and rollback, route add/list/remove, TLS configuration, config adaptation, status/health, metrics, PKI, and shutdown. Missing conveniences like a dedicated route update or config validation tool are mitigated by caddy_config_by_id and caddy_config_set, so there are no major dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Deploy full-stack apps (Postgres, Redis, S3, workers, backups) from Claude or curl. 59 MCP tools.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/YawLabs/caddy-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
