nginx-certbot-mcp

Overview Schema Source Related Servers Discussions Admin

create_site

Creates a new nginx server block for a domain, proxying to a specified upstream host and port. Validates configuration with nginx -t before applying, with automatic rollback on failure.

Instructions

Create a new nginx server block from the websocket-capable default template. Validates and test-renders (nginx -t) before touching live config, and rolls back automatically if the test fails. Does NOT reload nginx or request a certificate - follow with reload_nginx to go live, then issue_cert to get SSL. To point an existing site at a different upstream later, use update_site instead of recreating it. If a config for the domain already exists it is replaced - after being backed up (see rollback_site).

Input Schema

TableJSON Schema

Name	Required	Description
`domain`	Yes	Domain for the new server block, e.g. mysite.julcap.net
`upstream_host`	Yes	Hostname or IP nginx should proxy_pass to
`upstream_port`	Yes	TCP port on the upstream host

Output Schema

TableJSON Schema

Name	Required	Description
`success`	Yes
`config_path`	No	Present on success: absolute path of the written config
`test_output`	Yes	Output of `nginx -t` against the rendered config
`backup_created`	No	True if an existing config was replaced; it was backed up first (see rollback_site)
`reload_required`	Yes	True on success - nginx has not actually been reloaded yet

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.1.2Sep 19, 2026

addedOutput schema / properties / backup_created

Added value: +{
+  "description": "True if an existing config was replaced; it was backed up first (see rollback_site)",
+  "type": "boolean"
+}

Addedv0.1.1Sep 15, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses safety behaviors beyond annotations: runs `nginx -t` before touching live config, auto-rolls back on failure, and replaces existing configs only after backing them up via rollback_site. The annotations do not cover these details, so this is valuable added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Each sentence earns its place: purpose, safety validation, follow-on steps, alternative tool, and replace/backup behavior. The most important action is front-loaded and the wording is dense without being wordy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and detailed annotations, the description covers what the tool does, what it does not do, what happens on failure, how to handle existing configs, and the required follow-up steps. It gives an agent everything needed to invoke it correctly and sequence it with siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers all three parameters with full descriptions at 100% coverage, so the description does not need to repeat them. The description adds no extra parameter-level meaning, but the schema already carries that burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create a new nginx server block' from a particular template. It also distinguishes itself from sibling tools like update_site and the follow-on reload_nginx/issue_cert, making its role unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit sequencing: do NOT reload or get a certificate; use reload_nginx then issue_cert. Also names update_site as the alternative for re-pointing an existing site, giving clear when-to-use vs when-not-to guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.