# Caddy Server MCP for AI Agents MCP > The Caddy Server MCP lets you manage your entire web stack directly through chat. Use it to update complex configurations, check real-time proxy health, and handle SSL certificate chains without touching a terminal or writing boilerplate code. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** web-server, reverse-proxy, api-gateway, ssl-certificates, automation ## Description This MCP gives your AI client direct control over the inner workings of a running Caddy reverse proxy instance. Instead of logging into the API dashboard or wrestling with YAML files, you simply tell your agent what needs to happen—update a path, check an upstream endpoint, or rotate a certificate. You can load new server configurations using various formats, making it easy to adapt complex setups on the fly. It also lets you analyze existing structures by converting Caddyfile text into raw JSON for easier programmatic handling. Need performance data? Get Prometheus-style metrics and monitor specific backends' health status instantly. All this functionality is managed through a single connection point in the Vinkius catalog, meaning once your AI agent connects to Vinkius, it has access to all web infrastructure tools, not just this one. ## Tools ### append_config Adds or overwrites an element in a specific section of the overall Caddy configuration object. ### delete_config Removes a specified piece of data from any named path within the Caddy configuration structure. ### get_config_by_id Retrieves a specific, identifiable object or section of the full configuration using its unique ID field. ### adapt_config Converts Caddyfile text into valid JSON format, allowing you to review the structure without applying changes. ### get_config Exports the current configuration data for a specific path or provides the full server configuration as JSON. ### get_metrics Pulls performance and traffic metrics from the server, formatted in Prometheus standard text. ### get_pki_ca_certs Returns the full certificate chain details for a particular Certificate Authority (CA). ### get_pki_ca Provides information about a specific PKI application CA used by your web service. ### get_upstreams Checks and reports the current operational status of all configured proxy upstreams. ### insert_config Creates a new object or inserts data into an array at a precisely defined index in the configuration. ### load_config Sets or replaces the entire active Caddy server configuration using either native JSON or Caddyfile text. ### replace_config Strictly overwrites an existing object or array element in the Caddy configuration without adding new data. ### stop_server Shuts down the running Caddy process cleanly and safely, exiting the service. ## Prompt Examples **Prompt:** ``` I need to check the status of my main API cluster upstreams right now. ``` **Response:** ``` Checking proxy health... *Status Report: api-cluster* | Endpoint | Status | | :--- | :---: | | /v1/users | **Healthy** | | /v2/payments | *Timeout (Retry)* | The `/v2/payments` cluster is reporting intermittent timeouts. I recommend checking the full metrics for that upstream to see if it's a load issue or an actual service failure. ``` **Prompt:** ``` How do I convert this Caddyfile snippet into JSON format? ``` **Response:** ``` Here is the adapted structure based on your input: ```json { "servers": [ { "site": "example.com", "handler": { "reverse_proxy": "localhost:8080" } } ] } ``` Does this JSON structure look correct for what you need? ``` **Prompt:** ``` What is the full configuration and can I delete the old /api/v1 path? ``` **Response:** ``` I've retrieved the current config. It contains 3 HTTP servers and 5 routes. *Action:* To remove `/api/v1`, I used the `delete_config` tool. The old routing rule has been removed from the active configuration, leaving only the newer paths intact. ``` ## Capabilities ### Apply Configuration Changes Load entire server configurations or make specific adjustments by appending new rules or replacing existing values within the Caddy setup. ### Analyze and Adapt Configs Convert standard Caddyfile text into structured JSON format for review, without actually applying any changes to the live environment. ### Check Proxy Status Get real-time health reports on all configured proxy upstreams and backends, identifying immediate performance bottlenecks or timeouts. ### Inspect Security Certificates View details about the Certificate Authority (CA) and retrieve specific certificate chains for managed domains to ensure security compliance. ### Monitor Performance Metrics Access structured, time-series data metrics that show request traffic volume and general server performance over time. ## Use Cases ### Troubleshooting a Broken API Endpoint The agent detects that `/api/v2` is returning 503 errors. You prompt it to check the upstream status, which reveals a timeout on one node in the backend cluster. The agent then retrieves the full metrics data so you can determine if the issue is intermittent or sustained. ### Implementing a New Service Route A new microservice needs routing at `/user-data`. You provide the service's Caddyfile snippet and ask the agent to adapt it. After reviewing the JSON structure, you instruct the agent to load the new configuration, activating the route immediately. ### Emergency Certificate Rotation The primary domain certificate is expiring in three hours. You ask the agent for the current PKI CA details and the necessary certificate chain for validation, allowing you to prepare the renewal process instantly. ### Cleaning Up Old Routes A legacy API path needs to be deprecated. Instead of manually finding the old route in the config, you ask the agent to read the full configuration and then use `delete_config` to remove the specific entry. ## Benefits - Stop manually copying configuration blocks. You can use `load_config` or `replace_config` to update entire server settings, whether they're in JSON or Caddyfile format. - Diagnose failures faster by checking the real-time health of your backend services using `get_upstreams`, immediately seeing if a proxy target is timing out or down. - Simplify security audits. Instead of logging into multiple dashboards, use `get_pki_ca_certs` and `get_pki_ca` to gather all necessary certificate chain information in one prompt. - Eliminate guesswork during development. Use `adapt_config` to convert Caddyfile snippets to JSON for review before you ever hit 'apply'. - Monitor performance without writing monitoring queries. Simply call `get_metrics` and get Prometheus-style data on traffic volume and request counts instantly. ## How It Works The bottom line is that you manage complex web infrastructure changes and diagnostics entirely through conversational prompts. 1. Subscribe to this MCP on Vinkius and provide your Caddy Admin API URL (like http://localhost:2019). 2. Connect your AI client, giving it the necessary permissions to execute configuration commands. 3. Use natural conversation to tell your agent exactly what change you need—for instance, 'Check if my primary upstream is timing out,' or 'Update this path's headers.' The MCP handles the rest. ## Frequently Asked Questions **How do I use the Caddy Server MCP to fix a broken reverse proxy link?** You tell your agent which path is failing. It will run diagnostics, checking `get_upstreams` to pinpoint if the issue is with the target backend or the routing itself. You can then ask it to update the config using tools like `append_config`. **Can I use Caddy Server MCP to manage SSL certificates?** Yes, absolutely. The MCP handles certificate management for you. You can query details about the CA using `get_pki_ca`, and retrieve specific chains with `get_pki_ca_certs` whenever you need proof of compliance. **What is the easiest way to apply a large configuration change?** If you have a full, working config file, use `load_config`. You can feed it either pure JSON or the text version (Caddyfile), and the MCP will update your live services instantly. **Does Caddy Server MCP help with performance monitoring?** It does. Instead of logging into a separate metrics system, you prompt the agent to get Prometheus-style data via `get_metrics`. This gives you immediate visibility into request volume and server load. **Is this MCP only for testing configurations?** No. While it's great for development (using `adapt_config`), its main power is live, production management. You use it to modify or monitor real-world, actively running web services.