This server manages Ubuntu targets and PHP/Laravel/static app deployments through plan/apply workflows.
Inspect the configured Ubuntu host: OS, installed runtime commands, service states, and non-interactive sudo availability.
Plan and provision the host stack: resolve and install APT packages, enable PostgreSQL and Valkey, with stale plan rejection.
Register and list PHP applications with Git repository, branch, framework recipe, and frontend build configuration.
Plan and provision application resources: PostgreSQL database/role, Valkey namespace, and protected remote environment file.
Plan and deploy a registered application from Git using Deployer recipes, including framework migrations.
List retained releases and roll back to the previous good release.
Report systemd status for PostgreSQL, Valkey, or Caddy.
Generates Caddy site configurations for registered applications, validates the full Caddy configuration, reloads Caddy, and uses Caddy's local CA for HTTPS certificates.
Supports deployment of Next.js static exports via the out directory.
Builds static frontends and PHP frontend assets by running npm ci from the committed lockfile followed by a validated npm script.
Supports deployment of Nuxt-generated static sites via the .output/public directory.
Deploys registered PHP applications, configuring PHP-FPM and application public directories for serving.
Creates isolated per-app PostgreSQL roles and databases via local peer authentication, with passwords generated on the remote host.
Provisions and manages a fixed Ubuntu host, installing system packages and managing systemd services according to a declared stack manifest.
Supports deployment of Vite/static frontend applications, with configurable output directories and npm-based builds.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gimme MCP plan the stack before provisioning devbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gimme is an alpha MCP deployment control plane for Ubuntu targets. It keeps desired state locally, provisions a target through a narrowly scoped privileged helper, and deploys PHP/Laravel or static applications through Deployer.
Version 0.6 has four explicit resources:
a target is an independently provisioned Ubuntu machine;
an application is reusable source/build metadata;
a resource is a named, version-pinned PostgreSQL or Valkey service;
a deployment places one application revision on one target at one stage.
This is alpha software and 0.6 is a hard state/API break. There are no compatibility tools. The migration preserves existing remote paths, database identities, cache prefixes, and URLs while recording observed runtime and service versions explicitly.
Gimme deliberately exposes no arbitrary shell, SQL, hostname, package, service, or filesystem-path parameters. Remote mutations use reviewable, content-addressed plans. Applying a stale plan fails closed. Deployment placement is allocated once and cannot be changed through the update API.
Repository URLs must be credential-free. Authentication belongs in SSH agents, repository-scoped deploy keys, or credential helpers. The Deployer child receives an explicit environment allowlist, so unrelated shell credentials are not inherited.
Secrets are references such as my-deployment/STRIPE_KEY, never MCP arguments or
tool output. They are resolved from secrets.enc.json with SOPS, placed in an
owner-only temporary file, transferred to an owner-only remote temporary file, and
removed after environment reconciliation.
Create or edit the encrypted document with sops config/secrets.enc.json; its nested
JSON keys must match the references declared by deployments. Configure age through
SOPS_AGE_KEY_FILE or SOPS_AGE_KEY in the MCP server's environment.
Production is policy, not a branch convention. A production deployment requires:
a public_dns target and explicit domain;
an exact commit source;
APP_ENV=production and APP_DEBUG=false;
a health gate before and after the current-symlink switch.
Staging also requires debug off and a health gate. Local and preview deployments are less restrictive. Caddy uses its internal CA for local mDNS and automatic ACME HTTPS for public DNS.
Related MCP server: deployment-mcp
# From the repository root:
uv sync
composer installState defaults to config/state.json. Set GIMME_STATE_DIR to keep operational state
elsewhere; the directory contains:
state.json # schema-v3 targets, applications, resources, deployments, pins
secrets.enc.json # SOPS-encrypted secret values
.gimme.lock # local atomic-write lockOperational state and encrypted secrets are ignored in this public source repository
because even encrypted documents, hostnames, repository URLs, and secret key names can
reveal private inventory. To make state Git-backed, point GIMME_STATE_DIR at a
separate private repository. Legacy 0.4 manifests remain ignored for the same reason.
Copy the example for a new installation, or use the migration tools for an older installation:
call plan_state_migration;
review its preserved placements and effects;
pass its exact plan_id to apply_state_migration;
commit the resulting desired state only if that repository is intended to hold your operational inventory.
See config/state.example.json for the complete shape.
For a public target, use network.mode: "public_dns", omit mdns_name, declare one
or more literal expected_addresses, and give every deployment an explicit domain.
Planning verifies that DNS resolves to a declared address before Caddy is allowed to
request an ACME certificate.
For guided workflows, see:
SSH must work against bootstrap_hostname. For local targets, normal operations use
the advertised hostname, which lets host-specific SSH settings such as agent
forwarding apply consistently.
The MCP server never handles a sudo password. Perform the initial helper installation from a terminal:
uv run gimme-bootstrap-target devbox
uv run gimme-bootstrap-database devboxThis keeps one interactive terminal open for sudo and installs root-owned, policy-bound helpers. Later MCP reconciliations use only those exact sudo rules. Run the bootstrap command again after changing the target's stack policy or upgrading Gimme's helper implementation.
The second command grants the deployment user PostgreSQL CREATEDB and CREATEROLE;
they allow database lifecycle management but do not grant operating-system root.
For a local mDNS target, import the exported Caddy public root once on each development workstation. The CA private key never leaves the target:
scp devbox.local:/srv/gimme/apps/.caddy-local-root.crt /tmp/gimme-caddy-root.crtTrust only a CA retrieved from a target you control.
Every deployment declares exact runtime versions. A pin has a provider and a
version; Gimme never resolves ranges such as latest, ^22, or 8.4.*.
system selects an exact host binary and verifies its full version.
mise installs and executes that exact user-space runtime from
<apps_root>/.gimme/mise without shell activation.
bundled is valid only for npm, whose version is supplied by the selected Node.js.
Set target.runtimes.mise_version whenever any deployment uses mise and include
mise plus software-properties-common in the target stack. On Ubuntu 26.04 Gimme's
privileged helper enables only the fixed official ppa:jdxcode/mise source; it never
pipes a remote installer into a privileged shell. Use
plan_deployment_runtimes and apply_deployment_runtimes to review and install the
declared mise pins. Multiple Node.js, Bun, pnpm, Yarn, Python, Ruby, Go, and Java
versions can coexist because each deployment command runs through
mise exec tool@version.
PHP web deployments deliberately use the system provider: the exact PHP patch is
verified, Deployer uses /usr/bin/phpX.Y, Caddy uses
/run/php/phpX.Y-fpm.sock, and queue/Horizon/scheduler units use that same CLI.
Composer is also system-pinned so it cannot silently execute under another PHP.
Application php_extensions are exact required capabilities checked before deploy;
their packages remain part of the target's reviewed APT stack.
PostgreSQL and Valkey are named resources with explicit versions and deployment
bindings. The current target_local provider permits one version of each service per
target; the model leaves room for external or isolated providers later without
changing deployment identity.
Applications may select npm, pnpm, yarn, or bun. The deployment declares exact
runtime versions and verifies them before running a build. Gimme accepts
only a validated script name, never a free-form command, and requires exactly one
matching lockfile with no conflicting package-manager lockfiles.
Manager | Frozen install |
npm |
|
pnpm |
|
Yarn 1 |
|
Yarn 2+ |
|
Bun |
|
Gimme will not silently substitute a package manager or update a lockfile.
uv run gimme-mcpExample stdio client configuration:
{
"mcpServers": {
"gimme": {
"command": "uv",
"args": ["--directory", "/path/to/gimme", "run", "gimme-mcp"]
}
}
}Register or migrate targets, applications, resources, and deployments.
inspect_target, then plan_target_stack / apply_target_stack.
plan_deployment_runtimes / apply_deployment_runtimes to install and verify pins.
plan_deployment_resources / apply_deployment_resources to reconcile routing,
PostgreSQL, Valkey, runtime values, workers, Horizon, and the scheduler.
plan_deployment to review the resolved commit and Deployer task graph, then
apply_deployment with the exact plan.
Use list_releases, rollback_deployment, deployment-scoped Artisan tools, and
deployment_process_status for operations.
Use plan_promotion / promote_deployment to deploy the exact current commit from
one deployment to another. The destination source is pinned only after success.
Use plan_remove_deployment / remove_deployment for explicit cleanup.
Laravel candidate health runs inside the release before activation. The live HTTPS
health gate runs after activation and automatically restores the prior release on
failure. Queue workers use queue:restart; Horizon uses horizon:terminate, matching
Laravel's graceful restart model and avoiding a PHP-FPM reload.
Read-only resources:
gimme://state
gimme://targets/{name}
gimme://applications/{name}
gimme://resources/{name}
gimme://deployments/{name}
See docs/reference/mcp.md for the complete tool and resource
catalog. Runtime schemas returned by tools/list, resources/list, and
resources/templates/list remain authoritative.
Gimme 0.6 provides the multi-target foundation and strong production invariants. It still provisions target-local PostgreSQL and Valkey. Managed cloud databases, backups, HA, external secret stores, immutable build artifacts, traffic splitting, and fleet scheduling are intentionally future work rather than implied production guarantees.
# From the repository root:
bash scripts/gimme-verifyThe project is licensed under the MIT License.
Deploy a registered application from Git using its pinned Deployer recipe. Requires the current plan_id and may run framework migrations defined by that recipe.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| plan_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read/write and idempotency, and the description adds a meaningful side effect: 'may run framework migrations defined by that recipe.' It also notes the plan_id prerequisite, which is beyond the structured 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?
Two tightly worded sentences accomplish a lot: they define the operation, source, mechanism, prerequisite, and a key side effect. There is no filler or 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 an output schema and informative annotations, the description covers the essential call context: registered app, Git source, pinned recipe, required plan_id, and possible migrations. It could be slightly stronger by pointing to plan_deploy as the source of the plan_id, but the information present is enough for correct invocation in most cases.
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?
With 0% schema description coverage, the description partially compensates by explaining that plan_id must be the current plan and that the app must be registered. However, it never explicitly names or contextualizes the 'name' parameter beyond the schema's field name, leaving some inference required.
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 action: 'Deploy a registered application from Git using its pinned Deployer recipe.' This clearly identifies the verb, resource, and method, and distinguishes it from siblings like plan_deploy or rollback_app.
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 useful context: the app must already be registeredicut and the plan_id must be current. It implies this is the execution step after planning, though it does not explicitly name alternatives or say when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the configured Ubuntu host and report its OS, installed runtime commands, service states, and non-interactive sudo availability. Makes no changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output 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 by specifying exactly what the inspection covers (OS, runtimes, services, sudo) and explicitly states 'Makes no changes,' reinforcing the non-destructive nature. This goes beyond the annotations and gives the agent a clear expectation of the report content.
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, tightly-worded sentence that front-loads the action and scope, lists the key outputs, and ends with a clear non-mutating statement. Every clause earns its place with no fluff or repetition.
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 no-parameter, read-only inspection tool with an output schema (per context signals), the description is complete. It states what the tool reports and confirms it makes no changes. The agent has everything needed to invoke it correctly. The sibling tools are all about provisioning, deployment, or service status, so this tool's role is clearly positioned.
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 description has no need to explain parameter semantics. Per the rubric, 0 parameters gets a baseline of 4. The description does not attempt to explain any schema fields, which 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 clearly states the verb 'inspect' and the resource 'configured Ubuntu host', and specifies the exact outputs: OS, runtime commands, service states, and sudo availability. This distinguishes it from siblings like service_status, which focuses on services, and plan_stack/provision_stack which are about provisioning. The purpose is 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 this is a pre-flight inspection tool for checking host readiness, but it does not explicitly say when to use it versus alternatives. However, given it takes no parameters and is a read-only inspection, the usage context is fairly obvious. It could benefit from a hint like 'Use before provisioning or deployment,' but the intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List locally registered PHP applications and their Git repository, framework recipe, branch, and computed deployment path. Does not contact the host.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these by clarifying the operation is purely local and does not contact the host, which is a meaningful trait an agent should know before calling.
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 tight sentences with no filler. The main action and return fields are front-loaded, and the key behavioral caveat ('Does not contact the host') is appended without bloating the description.
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?
With an output schema present, no parameters, and rich annotations covering safety and idempotency, the description supplies the only missing context: local scope, the specific kind of applications, and the no-host-contact guarantee. Nothing essential is missing.
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?
There are zero parameters and schema description coverage is 100%, so the schema already exhaustively documents the input surface. The description adds no parameter details because none are needed; a baseline of 4 is appropriate for a parameterless tool.
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?
States a specific verb ('List') and resource ('locally registered PHP applications'), and enumerates the exact fields returned (Git repository, framework recipe, branch, computed deployment path). The 'Does not contact the host' clause differentiates it from host-inspecting siblings like inspect_host and service_status.
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?
Provides clear context that this operates on local registrations only and does not contact the host, which implies when it is appropriate versus tools that interact with the host. It stops short of explicitly naming alternatives or stating when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List retained releases for a registered application and identify the current release. Makes no changes.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 the behavioral detail of identifying the current release and scoping to retained releases, which goes beyond the annotations. It does not contradict the 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?
The description is two short sentences with the action front-loaded. It is concise, though the phrase 'Makes no changes' is redundant with the annotations. Still, it is efficient and free of 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?
With an output schema present, return values are covered. The description states the core purpose and a prerequisite (registered application). However, it fails to clarify the meaning of the sole parameter and does not explain what 'retained releases' means. For a simple read-only tool, this is adequate but leaves room for improvement.
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 0%, so the description must compensate for the undocumented 'name' parameter. However, the description does not explicitly state that 'name' refers to the application name. It only says 'for a registered application', leaving the parameter mapping to inference. This is a significant gap given zero coverage.
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 verb 'List' and the resource 'retained releases for a registered application', and adds the specific behavior of identifying the current release. It does not explicitly distinguish from sibling tools like list_apps, but the resource scope is distinct enough that an agent can infer the difference.
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 context: it is for a registered application, suggesting a prerequisite. However, it does not explicitly state when to use this over alternatives, nor does it mention exclusions. No alternative tools are referenced, so guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan a registered application's PostgreSQL database, database role, Valkey namespace, and protected remote environment file. Makes no changes.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description's 'Makes no changes' reinforces those hints but does not add new behavioral context beyond what annotations already provide. 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 a single sentence that front-loads the tool's purpose and immediately clarifies that no changes are made. Every phrase contributes useful information with no 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?
The description lists the exact resources planned and the non-mutating behavior, and an output schema exists. It is nearly complete, though it could add explicit usage guidance about when to pair it with provision_app_resources.
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 schema only defines a required string 'name' with no description. The description helps by indicating that 'name' refers to a registered application whose resources are being planned. It does not specify format or validation, but for a single simple parameter this adds meaningful semantic context.
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 ('Plan') and names the concrete resources involved: PostgreSQL database, database role, Valkey namespace, and protected remote environment file. It also clarifies scope by saying 'registered application', and the phrase 'Makes no changes' differentiates it from provisioning tools like provision_app_resources.
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 this is for planning rather than provisioning, especially given the sibling provision_app_resources. However, it does not explicitly state when to choose this tool over alternatives such as plan_stack or plan_deploy, nor does it mention prerequisites like the application needing to be registered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return Deployer's task execution plan for a registered application. Makes no remote changes and returns the current application plan_id for deploy_app.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output 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 description doesn't need to restate safety. It adds valuable context by specifying that it 'Makes no remote changes' and 'returns the current application plan_id,' which clarifies the exact output and reinforces the read-only nature. This goes beyond the annotations by describing the concrete return value, though it doesn't cover edge cases like unregistered apps.
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 with no unnecessary words. It front-loads the core purpose and immediately provides the key differentiator (no remote changes, returns plan_id for deploy_app). Every sentence adds value, and there is no redundancy with the annotations.
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 that an output schema exists, the description doesn't need to explain return structure, but it does mention the return value (plan_id). It covers the main prerequisites (application must be registered) and states the read-only behavior. It doesn't address error conditions or what happens if the app is not found, but that is likely covered by the output schema. For a single-parameter tool with rich annotations, this is sufficiently 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?
The schema has a single parameter 'name' with no description and 0% schema coverage. The description implies that 'name' refers to a registered application, but it does not explicitly state the parameter's meaning or format. While it provides some context, it doesn't fully compensate for the lack of schema documentation. An explicit note like 'name: the name of the registered application' would improve clarity.
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 function: 'Return Deployer's task execution plan for a registered application.' It specifies the resource (application) and the action (returning a plan). It distinguishes itself from siblings like plan_stack and plan_app_resources by focusing on the application-level plan and explicitly tying it to deploy_app, so an agent can tell it apart without opening schemas.
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 implicitly indicates when to use this tool: to obtain the plan_id needed for deploy_app. It does not explicitly mention alternatives or say 'use this before deploy_app,' but the phrase 'for deploy_app' clearly signals its purpose. There is no explicit exclusion of other tools, but the context is clear enough for an agent to infer its role in the deployment workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve every desired package against the configured host's current package metadata and return an exact provisioning plan. Unavailable packages make the plan unready. Makes no changes and returns a plan_id for provision_stack.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the unavailability condition ('Unavailable packages make the plan unready') and confirms it returns a plan_id, which is useful context beyond the annotations. No contradiction.
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 sentences, no waste, front-loaded with the main function and then the key non-mutating property. Excellent.
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 presence of an output schema and rich annotations, the description covers the core behavior: what it does, that it makes no changes, and the unavailability condition. It could be more explicit about when to use versus other planning tools, but that's a minor gap. Overall sufficient.
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?
No parameters exist (schema is empty), so baseline 4. The description adds that it uses the 'configured host's current package metadata', which explains the context of the operation. This adds meaning beyond the empty 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?
States a specific verb ('resolve') and resource ('desired packages against host's package metadata'), and clearly distinguishes itself from provision_stack by stating it returns a plan and makes no changes. The purpose is unmistakable.
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 mentions provision_stack as the follow-up, implying this is the pre-execution step. However, it doesn't explicitly contrast with other planning tools like plan_app_resources or plan_deploy, so it's clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a registered application's PostgreSQL database and role, generate its password on the host, and write PostgreSQL and Valkey settings to shared/.env. Requires a matching plan from plan_app_resources.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| plan_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false (write), destructiveHint=false (safe), idempotentHint=true (repeatable), and openWorldHint=true (side effects). The description adds value by specifying exactly what side effects occur: creating a database, role, password, and writing to .env. It also highlights the plan dependency. It doesn't contradict the annotations and provides contextual behavior 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 two sentences with no filler. The primary action is front-loaded, and the critical prerequisite is placed at the end. Every clause adds information, making it highly efficient.
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 operation's complexity (creating DB, role, password, writing env) and the presence of an output schema, the description covers the main actions and the key prerequisite. It doesn't mention return values, but the output schema handles that. It also doesn't discuss potential edge cases (e.g., existing resources), but the idempotentHint annotation mitigates that. Overall it's reasonably complete for an agent to invoke 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?
The input schema has zero description coverage, so the description must compensate. It gives a hint that 'name' refers to a registered application's name and that 'plan_id' is tied to a matching plan, but it does not explicitly explain the meaning of each parameter or any constraints. The description partially clarifies the parameters but leaves room for ambiguity about the exact format and relationship between name and plan_id.
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 ('Create') and clearly enumerates the resource being created: a PostgreSQL database and role, plus a password generation and settings write to .env. It also names the prerequisite plan, which distinguishes it from sibling tools like deploy_app and plan_app_resources, so an agent can identify its exact 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?
It explicitly states a required precondition: 'Requires a matching plan from plan_app_resources.' This tells the agent when it's appropriate to call this tool (after planning) and implies it should not be used before a plan exists. However, it does not name explicit alternatives or say when not to use it, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a previously returned stack plan to the configured host. Installs missing APT packages and enables PostgreSQL and Valkey; rejects stale or invented plan IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds specific behavioral details: it installs missing packages, enables services, and rejects invalid plan IDs. This clarifies side effects and error handling, which the annotations do not cover. It could also mention that it mutates host state, but that is implied by 'installs' and 'enables'.
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 with zero filler. The main purpose is front-loaded in the first sentence, and the second provides essential details and a rejection condition. Every word contributes value.
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 single-parameter tool with an output schema (present but not shown), the description fully covers the purpose, required context (a valid plan), side effects, and error behavior. Nothing an agent needs to call it correctly is missing.
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 0%, so the description must carry the burden. It clarifies that plan_id must be a previously returned plan ID and that stale/invented IDs are rejected. This adds semantic meaning beyond the bare schema definition, though it doesn't specify format or validation details.
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 ('apply'), a specific resource ('previously returned stack plan'), and concrete actions (installs APT packages, enables PostgreSQL and Valkey). This clearly distinguishes it from siblings like plan_stack (which creates plans) and provision_app_resources (which targets app resources).
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 context: it applies a plan that was previously returned, so the agent knows it must be called after plan_stack. It also notes it rejects stale or invented plan IDs, guiding the agent to only use valid IDs. It does not explicitly mention alternatives like provision_app_resources, but the resource type ('stack plan') is enough to differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register or update a PHP application's allowlisted deployment definition. Changes only the local registry; it does not connect to or modify the host.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| branch | No | main | |
| frontend | No | ||
| framework | No | common | |
| repository | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotency, read-write, and non-destructiveness. The description adds the valuable detail that it only affects the local registry and does not connect to or modify the host—beyond annotation coverage. This helps the agent understand side effects without contradiction.
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 with no fluff. It front-loads the core action and then clarifies scope, making it 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?
The description is clear about purpose and scope, but it leaves out parameter semantics and the meaning of 'allowlisted' deployment definition. Given the zero schema coverage and the presence of an output schema, the description is adequate for understanding what the tool does but not fully complete for invoking it correctly without additional context.
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 0%, so the description must compensate for explaining parameters. It does not mention any of the five parameters (name, repository, branch, frontend, framework) or their meanings. The description only states the overall purpose, leaving parameter usage completely undocumented.
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 (register or update), the target (PHP application's allowlisted deployment definition), and its scope (local registry only). It distinguishes from siblings like deploy_app and provision_stack by focusing on registration, and explicitly clarifies it does not touch the host.
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?
It gives clear context that this tool is for local registration, not host modification, which implies when to use it relative to deployment tools. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Roll a registered application back to its previous good Deployer release. Changes the live current symlink and marks the replaced release as bad.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| confirmation | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior, and the description adds concrete consequences: it changes the live current symlink and marks the replaced release as bad. This goes beyond the raw annotation and tells the agent what will actually be modified.
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 and front-loaded: the primary action comes first, followed by the side effects. Every sentence adds useful information and there is no filler or repetition of the title.
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?
While the core behavior is clear and an output schema exists, the tool is incomplete for safe invocation: the required confirmation parameter is undocumented, and there is no guidance on preconditions or error states. An agent would have to guess how to satisfy the confirmation requirement.
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 0%, and the description does not explain either required parameter. 'name' is only implied to be the application name, and 'confirmation' is completely unexplained – the agent cannot know what value should be supplied.
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 a specific action ('Roll a registered application back') and a precise target ('previous good Deployer release'), then names the concrete effects (changing the live symlink and marking the replaced release as bad). This clearly distinguishes it from deploy_app or list_releases.
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 rollback is used after a bad deployment to restore the previous good release, but it does not explicitly state when to use it versus deploying or inspecting releases, nor does it mention prerequisites like having a prior release or confirmation handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report systemd status for PostgreSQL, Valkey, or Caddy on the configured host. The service name is restricted to this allowlist and no changes are made.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds 'no changes are made' (redundant with annotations) and the allowlist (more parameter-related). No additional behavioral context such as error handling, authentication, or rate limits is provided.
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 every clause adds value. No extraneous information or repetition.
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 single-parameter tool with an output schema, the description covers the purpose, allowed inputs, and read-only nature. It does not describe output format, but the output schema handles that. Minor gap: no mention of prerequisite configuration, though 'configured host' implies it.
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 0%, but the description compensates by naming the three allowed services and explicitly stating the allowlist restriction. This adds human-readable meaning beyond the bare enum in 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?
The description states a specific action ('Report systemd status') on a defined resource ('PostgreSQL, Valkey, or Caddy on the configured host'). It clearly distinguishes itself from sibling deployment/provisioning tools by focusing on read-only status reporting.
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 status for the listed services) but does not explicitly state alternatives or when not to use it. The allowlist restriction is a constraint, not a routing to sibling tools.
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.
v0.1.0deploy_appinspect_hostlist_appslist_releasesplan_app_resourcesplan_deployplan_stackprovision_app_resourcesprovision_stackregister_approllback_appservice_statusScored across 12 tools
Each tool targets a distinct resource and action: host inspection, stack planning/provisioning, app registration, app resource planning/provisioning, deployment, releases, rollback, and service status. The plan/provision pairs are clearly separated by their plan/resource names and descriptions, so an agent should not confuse them.
Tool names follow a mostly consistent verb_noun snake_case pattern such as plan_stack, provision_stack, list_apps, deploy_app, and rollback_app. The only outlier is service_status, which uses a noun_noun form instead of a verb-first convention, but it is still readable and not confusing.
Twelve tools is well-scoped for a provisioning and deployment server. Each tool covers a meaningful step in the workflow, and none feel redundant or unnecessary.
The tool set covers the main lifecycle well: inspect, plan, provision, register, deploy, list releases, rollback, and check service status. The main gap is the lack of teardown or removal operations, such as unregistering an app or dropping provisioned resources, but most core workflows are fully supported.
Check if a repo will deploy, plan a deploy to your own cloud, and see status, logs and redeploys.
Deploy and manage applications, databases, domains, and git repos
Read apps and environments, and create them, on the fortrabbit PHP hosting platform.
Agent-first web hosting: deploy sites, apps, databases and domains over MCP.