Documentation

AI Assistants (MCP)

SnapDeploy's official MCP connector lets any Model-Context-Protocol client — Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI, Gemini CLI, Cline, Zed, VS Code agent mode — deploy and manage your containers from chat.

Setup

Create a token on the API Keys page — it generates the exact snippet for your assistant with the token filled in. The building blocks:

Claude Code

claude mcp add --scope user snapdeploy -e SNAPDEPLOY_API_KEY=sd_pat_… -- npx -y @snapdeploy/mcp

Cursor (~/.cursor/mcp.json) · Windsurf (~/.codeium/windsurf/mcp_config.json) · Gemini CLI (~/.gemini/settings.json) · any JSON-config client

{ "mcpServers": { "snapdeploy": { "command": "npx", "args": ["-y", "@snapdeploy/mcp"], "env": { "SNAPDEPLOY_API_KEY": "sd_pat_…" } } } }

Codex CLI (~/.codex/config.toml)

[mcp_servers.snapdeploy]
command = "npx"
args = ["-y", "@snapdeploy/mcp"]
env = { SNAPDEPLOY_API_KEY = "sd_pat_…" }

Optional: SNAPDEPLOY_READ_ONLY=1 exposes only the read tools. Restart the assistant session after adding the server.

Tokens and scopes

Use a scoped personal access token (sd_pat_…), not the legacy API key. Tokens are hashed at rest, shown once, expire when you choose (30/90/365 days or never) and revoke instantly. Scopes nest:

Scope	Allows
read	Status, logs, deployments, quota, repo list, env-var scan
deploy	read + create containers, deploy, set env vars, start/stop/wake, resize, assign a spare Always-On
manage	deploy + create add-ons (databases, Redis, RabbitMQ) and attach domains

A call outside the token's scope returns 403 INSUFFICIENT_SCOPE with requiredScope. Each token has its own rate-limit bucket, so a runaway assistant throttles itself, not your account.

Tools

list_apps · get_status · get_logs · get_deployments · check_quota · list_repos · detect_env_vars

read

deploy (repo, branch, env, port, size) · set_env · start_container · stop_container · wake_container · assign_always_on

deploy

create_database · add_domain

manage

There are no delete tools and no SmartFix-apply tool.

deploy creates the container if needed, links the repo (which starts the build), waits, and returns the live URL — or the error code, message and build-log tail. It is retry-safe: an identical request within ten minutes returns the original deployment.

Safety model

Deletion is impossible for any token. Deleting containers, add-ons, domains or the account, changing the password, cancelling subscriptions and applying SmartFix commits all return 403 INTERACTIVE_SESSION_REQUIRED — server-side, regardless of scope. A person signed in to the dashboard or app does those.
Secrets are never returned to tokens. Environment variables come back as names with values replaced by "(set)"; add-on credentials are masked.
Tenant isolation — a token only ever sees its own account's resources.
Plan limits are product moments, not errors. 402/429 replies carry SnapDeploy's message and purchase link; the connector instructs the assistant not to retry.

Scripting without an assistant

The same token works against the REST API (reference). Two conveniences added for automation:

# one-call deploy: create + link + first build
curl -X POST -H "X-API-Key: sd_pat_…" -H "Content-Type: application/json" \
  -d '{"repo":"you/your-repo","branch":"main","size":"small"}' \
  https://snapdeploy.dev/api/mobile/deploy

# retry-safe redeploy of a linked repo
curl -X POST -H "X-API-Key: sd_pat_…" -H "Idempotency-Key: release-42" \
  https://snapdeploy.dev/api/mobile/github/link/{repoLinkId}/deploy

Troubleshooting

"command not found: claude" — the standalone CLI isn't installed (the VS Code extension bundles its own). npm install -g @anthropic-ai/claude-code, then open a new terminal.

Server shows connected but tools don't appear — restart the assistant session; servers added mid-session need a reload.

401 Unauthorized — the token is revoked, expired or mistyped. Create a new one on API Keys and update SNAPDEPLOY_API_KEY.

403 INSUFFICIENT_SCOPE — the token lacks the scope named in requiredScope; mint one with that scope.

"GitHub is not connected" — open the link the reply gives you and authorize once; deploys need a connected GitHub account.

Supported Technologies Troubleshooting