nginx-certbot-mcp

Overview Schema Source Related Servers Discussions Admin

update_site

Idempotent

Rewrite an existing site's proxy_pass to a new upstream host and port in place, leaving SSL/certbot config untouched. Fails safely if no existing config or proxy_pass exists, and rolls back automatically if nginx -t fails.

Instructions

Update an existing site's upstream by rewriting its proxy_pass directive(s) in place - everything else in the config, including any SSL server block issue_cert/certbot added, is left untouched. Fails if the domain has no existing config (use create_site instead) or has no proxy_pass directive to update. Test-renders before keeping the change and rolls back automatically if nginx -t fails. Does NOT reload nginx - call reload_nginx afterward.

Input Schema

TableJSON Schema

Name	Required	Description
`domain`	Yes	Domain of the existing site to update
`upstream_host`	Yes	New hostname or IP nginx should proxy_pass to
`upstream_port`	Yes	New TCP port on the upstream host

Output Schema

TableJSON Schema

Name	Required	Description
`success`	Yes
`test_output`	Yes	Output of `nginx -t` against the rewritten config, or an explanatory message if nothing was changed
`reload_required`	Yes	True on success - nginx has not actually been reloaded yet

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.1Sep 15, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (idempotent, non-destructive), the description reveals critical behavioral traits: it rewrites proxy_pass in place, preserves SSL config, test-renders before committing, and auto-rolls back on nginx -t failure. It also discloses the lack of reload. These details significantly 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.

Conciseness5/5

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

The description is efficient and front-loaded with the core action and key constraints. Every sentence carries essential information (scope, failure conditions, safety mechanism, post-requisite), with zero fluff or repetition.

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?

The description covers failure conditions, the test-render/rollback mechanism, the reload requirement, and what is left untouched. With an output schema present and annotations providing safety hints, an agent has everything needed to invoke this tool correctly and predict its outcomes.

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

Parameters4/5

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

Schema coverage is 100%, so each parameter is already documented. The description adds value by linking the parameters to the operation (domain identifies the existing site, upstream_host/port become the new proxy_pass target), reinforcing their roles. This extra context elevates it above the baseline 3.

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?

The description clearly states the verb 'Update', the resource 'existing site's upstream' via proxy_pass rewriting, and explicitly differentiates from create_site and reload_nginx. It specifies exactly what is modified and what remains untouched, leaving no ambiguity about the tool's purpose.

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?

The description explicitly states when to use this tool (existing site with proxy_pass) and when not to (if no existing config, use create_site instead; does not reload, call reload_nginx afterward). It names the alternatives directly, providing unambiguous routing for an agent.

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