Allows listing GitHub repositories and deploying them to SnapDeploy, with support for environment variable detection and deployment management.
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., "@@snapdeploy/mcp Deploy the GitHub repo acme/web to SnapDeploy and share the live URL"
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.
Deploy and manage SnapDeploy containers from your AI assistant — Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI, Gemini CLI, or any client that speaks the Model Context Protocol over stdio.
Say "deploy this repo to SnapDeploy" and get a live URL back. Builds, logs, environment variables, managed databases and custom domains — without leaving the chat.
Sign in at snapdeploy.dev, open API Keys and create a
token with the deploy scope (the page generates the snippets below with your token
already filled in).
Add the server to your client:
Claude Code
claude mcp add --scope user snapdeploy -e SNAPDEPLOY_API_KEY=sd_pat_your_token -- npx -y @snapdeploy/mcpCursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json),
Gemini CLI (~/.gemini/settings.json), Claude Desktop and other JSON-configured clients:
{
"mcpServers": {
"snapdeploy": {
"command": "npx",
"args": ["-y", "@snapdeploy/mcp"],
"env": { "SNAPDEPLOY_API_KEY": "sd_pat_your_token" }
}
}
}Codex CLI (~/.codex/config.toml):
[mcp_servers.snapdeploy]
command = "npx"
args = ["-y", "@snapdeploy/mcp"]
env = { SNAPDEPLOY_API_KEY = "sd_pat_your_token" }Claude Code plugin (token stored in secure storage instead of a config file):
/plugin marketplace add AAR-Labs/snapdeploy-mcp
/plugin install snapdeploy@snapdeployRestart the session; the snapdeploy tools appear. Your repository must be on GitHub and
GitHub must be connected to SnapDeploy once (the connector returns the link if it isn't).
Related MCP server: Liara MCP Server
Scope | Tools |
|
|
|
|
|
|
Scopes nest (read ⊂ deploy ⊂ manage); the server enforces them before any tool runs.
There is no delete tool, and the server refuses deletes, subscription cancellations and
password changes for every token — those need a person signed in to the dashboard or the
mobile app.
Nothing destructive, ever. Even an agent that escalates to a raw API call with the
same token gets 403 INTERACTIVE_SESSION_REQUIRED.
Secrets never reach the model. Environment-variable values come back as (set)
and credentials are masked — on the server, not just in this connector.
Scoped, expiring, revocable tokens with their own rate limit. Revoke on the API Keys page and every request returns 401 from that moment.
Retry-safe deploys. Identical requests inside ten minutes return the original deployment instead of starting another build.
Plan limits are relayed, not retried. 402/429 replies carry SnapDeploy's own message and upgrade link, and the assistant is told not to retry.
Variable | Required | Meaning |
| yes | Scoped token ( |
| no |
|
| no | Defaults to |
Guides: Claude Code · Cursor · Codex / Gemini CLI · Lovable exports
Reference: snapdeploy.dev/docs/mcp · API
Design write-up: why an agent that can deploy must not be able to delete
MIT © AAR Labs
Attach a custom domain to a container. Returns the DNS records the user must create; verification then runs from the SnapDeploy UI.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | e.g. app.example.com | |
| container | Yes | Container name or id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool returns DNS records the user must create and that verification runs later from the SnapDeploy UI, which gives the agent useful expectations about asynchronous follow-up. It does not address edge cases like replacement or reversal, but it covers the core behavior well.
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 the main action front-loaded and the important return/verification behavior following immediately. Every sentence earns its place 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 is adequate for a simple two-parameter tool: it states the action, the required user follow-up (DNS records), and the verification path. It could mention constraints like allowed domain formats or idempotency, but those are not essential for a basic correct call.
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 both parameters are already documented in the schema. The description adds the result detail (DNS records) but does not deepen the meaning of the domain or container parameters themselves, so the 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 and resource: 'Attach a custom domain to a container.' The action and object are unambiguous and clearly distinguish this from container lifecycle, list, and deployment tools in the sibling set.
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 what the tool does but does not state when to use it versus alternatives or mention any prerequisites or exclusions. There is no explicit guidance such as 'use this when...' or 'do not use this if...'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach an UNASSIGNED Always-On subscription to a container (keeps it running 24/7 and lifts the deploy limit). Only call this after the user explicitly confirms — check_quota lists any unassigned subscriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| container | Yes | Container name or id | |
| subscription_id | Yes | From check_quota or a 402 reply's spareSubscriptionId |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains the post-assignment effects (24/7 running, lifted deploy limit) and the requirement that the subscription be unassigned. It could also mention reversibility or failure behavior, but the key behavioral traits are present.
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. It front-loads the core action and effect, then adds the critical usage guardrail and input source. Every clause 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 two-parameter tool with fully documented schema properties, the description provides enough context to select and invoke it correctly: the action, the effect, the prerequisite, and the source of valid inputs. It does not describe response shape or edge cases, but those are minor gaps for this simple operation.
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 input schema already documents both subscription_id and container. The description reinforces that unassigned subscriptions come from check_quota, but it does not add substantial semantic 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 uses a specific verb and resource: 'Attach an UNASSIGNED Always-On subscription to a container.' It also states the functional effects (keeps it running 24/7 and lifts the deploy limit), which clearly sets it apart from sibling tools like stop_container, deploy, or check_quota.
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 an explicit precondition: 'Only call this after the user explicitly confirms.' It also points to the exact sibling tool, check_quota, for discovering unassigned subscriptions, so an agent knows how to gather the required input before calling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Can the user deploy and run apps right now? Merges the deploy limit (5 per rolling 12h — ONLY for accounts without an Always-On/Sprint entitlement; failed attempts count) and the free-hours cap (containers refuse to start at 402 when exhausted), plus any unassigned Always-On subscriptions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It does an excellent job revealing the underlying logic: the 5-per-rolling-12h deploy limit applies only to accounts without entitlement, failed attempts count, containers refuse to start at 402 when free hours are exhausted, and unassigned Always-On subscriptions factor in. It stops short of stating that the tool is read-only, but the name 'check' and the lack of mutation language make that reasonable to infer.
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 efficient. It leads with the core question, then adds necessary detail about the two limits and the Always-On caveat. Every clause carries useful information — no filler. It could be slightly more compact, but the specificity justifies the length.
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 has no output schema, so the description should clarify what the tool returns. The question 'Can the user deploy and run apps right now?' implies a boolean answer, but the phrase 'Merges the deploy limit... and the free-hours cap... plus any unassigned Always-On subscriptions' suggests the result may be more structured (e.g., breakdown of limits). This is not explicitly described, leaving an agent uncertain about the return format. The logic is well covered, but the missing return specification is a notable gap.
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 baseline is 4. The description does not need to explain parameter semantics, and it doesn't attempt to; it focuses entirely on the tool's behavior and output, 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 opens with a direct question that captures the tool's purpose — 'Can the user deploy and run apps right now?' — and then specifies exactly what it merges: the deploy limit, the free-hours cap, and unassigned Always-On subscriptions. This is specific and clearly distinguishes it from siblings like deploy, get_status, or assign_always_on.
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 the tool is used to check whether deployment or app start will succeed given quota limits, but it does not explicitly say 'use this before calling deploy or start_container' or name alternative tools. The context is clear, but there are no explicit exclusions or routing to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a managed add-on: PostgreSQL, MySQL, MariaDB, MongoDB, Redis or RabbitMQ. Requires a purchased add-on subscription — without one this returns the purchase link (relay it, don't retry). Credentials are provisioned server-side and shown to the user in the SnapDeploy UI, never through this connector.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Add-on name | |
| type | Yes | Engine — POSTGRESQL is accepted as an alias of POSTGRES | |
| container | No | Container to link it to (name or id) | |
| database_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the operation requires a subscription, that it may return a purchase link instead of performing the action, and that credentials are provisioned server-side and shown in the UI—not returned through the connector. This is substantial transparency, though it doesn't detail whether the operation is synchronous, what the success response looks like, or if there are side effects beyond creation.
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 long, front-loads the core purpose, and includes essential behavioral details (subscription requirement, credential handling) without any fluff. Every sentence earns its place, making it an exemplar of concise, structured documentation.
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 and no annotations, the description covers the key operational aspects: what it creates, the prerequisite, the failure mode, and where credentials appear. It doesn't mention the response format or success indicators, but given the description's focus on critical behaviors and the absence of complex parameters, it is sufficiently complete for an agent to call 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 schema already documents three of four parameters (name, type, container) with descriptions, leaving only database_name without a description. The tool description adds no additional parameter meaning—it doesn't explain what 'database_name' is for or clarify any parameter interactions. Given the high schema coverage (75%), the baseline of 3 is appropriate; the description doesn't need to repeat schema info but could have added context for the undocumented parameter.
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: creating a managed add-on for specific database engines. It lists the engines explicitly (PostgreSQL, MySQL, etc.), making the purpose unambiguous and distinct from sibling tools like stop_container or deploy, which focus on other operations.
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 a clear prerequisite (purchased subscription) and instructs the agent on the expected behavior when that prerequisite isn't met (relay the purchase link, don't retry). While it doesn't explicitly name alternative tools, the context of sibling tools makes it obvious when this tool is appropriate—there is no sibling for database creation. This is solid usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploy a connected GitHub repo to SnapDeploy: creates the container if needed, links the repo, builds, and waits for the result. Reply includes the live URL or, on failure, the error and build-log tail. On accounts without an Always-On/Sprint entitlement this uses one unit of the deploy limit (failed attempts count); Always-On accounts are uncapped.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Environment variables to set before building (VITE_*/public-prefixed ones are applied at build time) | |
| port | No | App port if auto-detection needs an override | |
| repo | Yes | owner/name of a repo on the user's connected GitHub | |
| size | No | Container size: small (512 MB, free) | medium (2 GB, needs a STARTER Always-On) | large (4 GB, needs a PRO Always-On). Default small. If the account lacks the entitlement the platform returns its upgrade link — relay it, do not retry or silently fall back to small. | |
| branch | No | Branch to deploy (default: repo default branch) | |
| container | No | Container name (default: repo name, lowercased) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosureen it does exceptionally: it reveals side effects (creates container, links, builds, waits), the return behavior (live URL or error with build-log tail), and quota semantics (deploy limit usage, failed attempts count, uncapped for Always-On). These are material behaviors beyond the input schema.
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, each earning its place: purpose, outcome, and quota/entitlement caveat. The most decision-relevant information is front-loaded, and there is no redundant or vague wording.
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 prerequisites (connected repo), process, wait behavior, success/failure response shape, and resource consumption. Since no output schema exists, explaining the return payload is necessary and done well. The schema handles parameter-specific edge cases like upgrade links and fallback prohibition.
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 schema already documents every parameter in detail. The description adds process-level context (e.g., that building happens and result is awaited) but does not add per-parameter meaning; 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 opens with a precise verb and resource: 'Deploy a connected GitHub repo to SnapDeploy.' It outlines the full operation (creates container, links repo, builds, waits), clearly distinguishing this high-level action from sibling tools like list_apps, get_status, or start_container.
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?
Clear context is provided: this tool is for deploying a connected repo incl. container creation, linking, building, and waiting. It does not explicitly name alternatives or state when-not-to-use, so it misses the 'explicit exclusions/alternatives' bar, but the intended usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a repo for the environment variables it needs (import.meta.env / process.env usage). For known keys (Supabase etc.) the reply says where the user finds the value. Do this BEFORE the first deploy of a Lovable/Bolt/v0 export.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | owner/name | |
| branch | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does convey a read/scan-oriented behavior and discloses that replies include where the user can find known values (e.g., Supabase). However, it does not describe output shape, branch behavior, or operational constraints, leaving several behavioral aspects unspecified.
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 a front-loaded core action. It contains no filler; each clause contributes either scope, output behavior, or timing guidance.
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 tool with one required parameter, the description is largely complete: it states the purpose, the input, when to run it, and partial output behavior. The main gap is the unaddressed branch parameter and a fuller description of the return payload, but the absence of an output schema and the tool's straightforward nature keep this from being a major issue.
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 only 50%: 'repo' is described as owner/name but 'branch' has no description. The tool description adds no parameter-level meaning and never mentions the optional branch parameter or its effect. Given partial schema coverage, the description should compensate but does not.
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 action ('Scan a repo'), a concrete resource ('a repo'), and the exact detection scope (import.meta.env / process.env usage). It also distinguishes the tool's role by tying it to the deploy flow, which helps separate it from siblings like deploy and set_env.
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 says when to run this tool: 'Do this BEFORE the first deploy of a Lovable/Bolt/v0 export.' This is concrete and actionable. However, it does not mention when not to use it or name alternatives such as set_env, so exclusions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deployment history of a container, or one deployment in detail (status, error code/message and build-log tail — use this to diagnose a failed build).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | List size, default 10 | |
| container | No | Container name or id (for the list) | |
| deployment_id | No | One deployment in detail |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does it well by disclosing the returned information for the detail view: status, error code/message, and build-log tail. The wording 'history' and 'detail' implies a read-only diagnostic operation; it does not mention pagination or no-parameter behavior, but no mutation or unexpected side effects are hidden.
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?
One compact sentence that front-loads the resource and modes before the parenthetical diagnostic detail. There is no filler or redundant restating of the tool name.
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 two main call modes and the diagnostic use case, which is the core context needed. It leaves some ambiguity around required/absent identifiers (container and deployment_id are both optional in the schema) and does not describe the fields returned in the list view, and there is no output schema to fill that gap.
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 meaning by explicitly associating container with the historical list and deployment_id with the detailed diagnostic output. It also names the fields an agent can expect when using deployment_id, which the schema does not.
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 deployments as the resource and distinguishes a list-style history from a single-deployment detail view, including concrete output fields (status, error code/message, build-log tail). It does not explicitly name a sibling tool, but the diagnostic use case makes the purpose distinct from get_logs/get_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?
It gives a concrete trigger—'use this to diagnose a failed build'—which tells the agent when the detail view is relevant. It does not provide explicit when-not-to-use or alternative tool names, but the context is clear enough to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent RUNTIME logs of a container (CloudWatch, up to 1000 lines). For BUILD logs of a deployment use get_deployments with a deployment_id.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | No | Line count, default 100 | |
| container | Yes | Container name or id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the source (CloudWatch), scope (runtime logs), and a line cap (up to 1000 lines), but it does not describe ordering, error behavior, or what happens when the container does not exist. These gaps keep it slightly below strong behavioral transparency.
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 with no filler. The primary purpose is front-loaded, and the alternative is delivered in a tightly targeted second sentence.
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 two-parameter log retrieval tool with no output schemahare, the description covers purpose, source, limit, and sibling routing. It lacks only minor behavioral details like log ordering or error handling, which are not essential for correct 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?
The schema already fully documents both parameters (container name/id and line count with default 100). The description adds 'CloudWatch' and 'up to 1000 lines', but this mostly repeats the schema's maximum constraint. With 100% schema coverage, the baseline 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 states a specific verb and resource: 'RUNTIME logs of a container'. It also explicitly distinguishes itself from the sibling get_deployments, making the tool's scope immediately 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?
It explicitly tells the agent when to use this tool versus the alternative: 'For BUILD logs of a deployment use get_deployments with a deployment_id.' This provides both a condition and a concrete alternative, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full status of one container (by name or id): state, URL, port, detected technology, resources. Env-var VALUES are never returned — names only.
| Name | Required | Description | Default |
|---|---|---|---|
| container | Yes | Container name or id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It explicitly discloses that environment variable values are never returned—only names—which is a meaningful privacy/security behavior. The read-only nature of 'status' is also clear from the description.
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 deliver all necessary information with no filler. The core purpose and return fields are front-loaded, followed by a concise security-relevant caveat. Every word 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 simple single-parameter read tool, the description is complete: it identifies the input and enumerates the output fields. Since there is no output schema, the explicit list of returned information is valuable and sufficient for an agent to understand what the call will provide.
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 the single parameter 'container' is already described as 'Container name or id'. The description repeats this by saying 'by name or id', adding no substantial semantic detail beyond the schema, so the baseline 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 clearly states a specific verb and resource: returning the full status of one container by name or id. It enumerates the returned fields (state, URL, port, detected technology, resources), making its purpose unambiguous and distinct from sibling tools like list_apps or get_logs.
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 clearly frames when this tool is appropriate: when you need comprehensive status for a single container. It does not explicitly name alternatives or exclusions, but the singular 'one container' provides clear context and implies that batch or log-specific needs belong to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's SnapDeploy containers with status and URL, plus plan, deploy-limit and free-hours state. Start here to find container ids/names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the operation (list), the scope ('user's'), and the returned state fields, which is sufficient for a simple read-only list tool. It could be more explicit about side-effect-free behavior or result format, but 'List' plus the data description is a clear behavioral statement.
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 compact sentences: the first lists what the tool returns, and the second states its primary use. No filler or repetition; the content is front-loaded.
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 parameterless list tool with no output schema, the description is complete: it names the resource, the user scope, the returned fields, and the recommended entry-point usage. An agent has everything it needs to select and call this tool 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 tool has zero parameters, so there are no parameter meanings to document. This matches the baseline 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?
Description opens with a specific verb and resource: 'List the user's SnapDeploy containers' and enumerates the exact data returned (status, URL, plan, deploy-limit, free-hours, ids/names). This clearly distinguishes it from sibling list_repos, get_deployments, and check_quota.
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?
'Start here to find container ids/names' gives explicit guidance that this is the entry point for container operations. It does not explicitly name alternatives or when-not-to-use cases, but the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List (or search) the GitHub repositories connected to this SnapDeploy account. If GitHub is not connected yet, returns the connect link for the user.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| query | No | Search text; omit to list |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It usefully discloses the not-connected edge case (returns a connect link), but it does not state that the operation is read-only, how pagination works, authentication requirements, or what the success response contains.
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 written sentences with the main action front-loaded and zero filler. Every sentence adds useful information.
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 has no output schema and no annotations, so the description must explain return behavior; it only covers the connect-link case. The page parameter is left undocumented, and the normal successful response format is not described, leaving an agent to guess.
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 only 50%: query has a description but page has none. The description adds no parameter detail beyond the schema, especially failing to explain the page parameter or pagination behavior.
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 names the specific verb and resource: list or search the GitHub repositories connected to the SnapDeploy account. It clearly differentiates from sibling tools like list_apps by scoping to GitHub repositories and the account connection.
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 usage context is implied: call this when you need the account's connected GitHub repositories, and the connect-link sentence covers the not-connected case. However, there is no explicit guidance about when to prefer this over sibling tools or when to use list versus search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set/replace a container's environment variables (rolling restart, no rebuild). Values are accepted but NEVER echoed back. Public build-time names (VITE_*, NEXT_PUBLIC_*, REACT_APP_*) only take effect in the bundle after the next deploy.
| Name | Required | Description | Default |
|---|---|---|---|
| env | Yes | Full desired map of env vars | |
| container | Yes | Container name or id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well. It discloses that env vars are set/replaced, that a rolling restart occurs without rebuild, that values are never echoed back, and that build-time vars are deferred until the next deploy. These are exactly the non-obvious behaviors an agent needs to know.
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 core action and restart behavior are front-loaded, followed by the security caveat about echoing and the build-time deploy timing note. 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 mutation tool with no annotations and no output schema, this description covers the most decision-relevant behavior: restart mechanics, rebuild implications, echo behavior, and deploy timing. It does not explicitly state what happens to omitted env keys or how success/failure is reported, but it is sufficient for correct 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?
The input schema already describes both parameters fully (100% coverage), so the baseline is 3. The description adds behavioral caveats but no additional parameter-level syntax or value-format information beyond what the schema provides.
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 and resource ('Set/replace a container's environment variables') and immediately differentiates itself with 'rolling restart, no rebuild'. This makes the tool's purpose and scope unmistakable, even alongside deploy-related siblings.
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 operational context: changes are applied via rolling restart without rebuild, and public build-time variables only affect the bundle after the next deploy. This implies when to prefer deploy for build-time vars, though it does not explicitly name the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a stopped container. May answer 402 when free hours are exhausted — relay that message and link, do not retry.
| Name | Required | Description | Default |
|---|---|---|---|
| container | Yes | Container name or id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full disclosure burden. It transparently discloses a quota-related failure mode (402 when free hours are exhausted) and prescribes the correct agent behavior (relay, do not retry). This goes beyond a bare restatement of the tool's name and adds useful operational context, though it doesn't describe permissions or success responses.
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 no wasted words. The primary purpose is front-loaded, and the critical error-handling note follows immediately. 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 single-parameter utility tool with no output schema, the description covers the core action and the most important exceptional behavior. It leaves out minor details like success response format, but those are not schema-required and the low complexity makes the description 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?
Schema coverage is 100%, with the parameter 'container' already described as 'Container name or id'. The description 'Start a stopped container' adds no further parameter-level meaning beyond what the schema provides, 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 states a specific action and target resource: 'Start a stopped container.' This is clear and distinct from stop_container. However, it does not explicitly differentiate from the sibling wake_container, which may overlap in functionality, so it stops short of a 5.
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 'stopped container' gives a clear condition for when to use the tool. The additional instruction about the 402 error — relay the message/link and do not retry — provides explicit behavioral guidance for a specific failure case. It lacks a directly named alternative tool, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running container (safe, reversible — deletion is NOT possible through this connector by design).
| Name | Required | Description | Default |
|---|---|---|---|
| container | Yes | Container name or id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden, and it does well by explicitly noting the operation is safe, reversible, and cannot delete anything 'by design.' This goes beyond minimal expectations, although it stops short of detailing side effects like state changes or idempotency.
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?
One tight sentence front-loads the action and adds a valuable safety note without redundancy. Every word 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 simple one-parameter tool, the description is quite complete: action, target state, safety, and reversibility are all addressed. It could mention expected return output or behavior on an already-stopped container, but these are minor for a straightforward stop operation.
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 covers the single parameter with a clear description ('Container name or id'). The description adds no extra meaning beyond this, so the baseline of 3 applies.
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 verb ('Stop') and resource ('a running container'), making the tool's function instantly identifiable. The parenthetical about safety and reversibility further differentiates it from destructive operations and 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 clearly establishes context: use it to stop a running container despite no explicit alternative references. Sibling tools like start_container and wake_container make the contrast implicit, but the description could have explicitly stated 'To start, use start_container' for stronger routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wake a sleeping free-plan container so its URL serves again.
| Name | Required | Description | Default |
|---|---|---|---|
| container | Yes | Container name or id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It communicates the state transition (sleeping -> serving again) and the intended effect, but it does not mention what happens if the container is already awake, whether there is a delay, or any side effects. This is adequate but not richly transparent.
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 communicates what the tool does, the target resource, and the expected outcome with no unnecessary words. It earns a top score for conciseness and structure.
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 simple with only one required parameter and no output schema, so the description covers the core action. However, it omits useful context such as how to confirm success, what failure modes exist, or whether waking has cost or time implications. This is serviceable for a minimal tool but not 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%, and the parameter 'container' is already described as 'Container name or id' in the schema. The description adds no further parameter-level meaning beyond the context that it applies to a sleeping free-plan container, so the baseline score of 3 applies.
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 ('Wake') and a specific resource ('free-plan container') plus the intended outcome ('so its URL serves again'). It clearly distinguishes this from sibling tools like start_container or stop_container by focusing on the sleeping/free-plan state.
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 this tool: when a container is sleeping on a free plan. It does not explicitly name alternatives or provide exclusion criteria, so it loses one point, but the condition is concrete enough for an agent to select it correctly.
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.0add_domainassign_always_oncheck_quotacreate_databasedeploydetect_env_varsget_deploymentsget_logsget_statuslist_appslist_reposset_envstart_containerstop_containerwake_containerScored across 15 tools
Tools are mostly separated by resource and action: list/get for reads, deploy/set_env for writes, and lifecycle verbs for container states. The only real overlap is start_container vs wake_container, but their descriptions (stopped vs sleeping free-plan) make the distinction usable.
Names follow a consistent snake_case verb_noun convention such as list_apps, get_status, start_container, and add_domain. The one-word deploy action is a minor deviation, but the overall pattern is predictable and easy to navigate.
15 tools is at the upper end of the typical range but each maps to a distinct platform operation, from deployment and env config to quota and add-ons. There is no filler; the size is well-scoped for the server's purpose.
The core workflow is well covered: connect repo, detect env vars, deploy, monitor logs/deployments, manage container state, set env, add domain, and check quota. Gaps like container deletion, database listing/removal, and domain removal are intentionally deferred to the SnapDeploy UI or noted as by-design limitations.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
