Official MCP connector
Terminal agents get the same deploy, logs, env-var and add-on tools as Claude Code and Cursor — with a scoped token and a live URL in the reply.
Add to ~/.codex/config.toml, then restart Codex.
[mcp_servers.snapdeploy]
command = "npx"
args = ["-y", "@snapdeploy/mcp"]
env = { SNAPDEPLOY_API_KEY = "sd_pat_your_token" }
Add under mcpServers in ~/.gemini/settings.json, then restart Gemini CLI.
{
"mcpServers": {
"snapdeploy": {
"command": "npx",
"args": ["-y", "@snapdeploy/mcp"],
"env": { "SNAPDEPLOY_API_KEY": "sd_pat_your_token" }
}
}
}
Get the token on the API Keys page after signing in — it generates both blocks with your token filled in. Your repo must be on GitHub and connected to SnapDeploy once.
Codex CLI and Gemini CLI are built to run with less supervision than an editor: you give them a goal and they work through it, calling tools as they go. That changes what a deploy connector has to guarantee.
Agents retry. Every deploy call carries an Idempotency-Key; an identical request inside ten minutes returns the original deployment instead of starting a second build — and does not consume another deploy unit.
Each token has its own rate bucket (150 requests a minute). A runaway loop throttles that one token; your dashboard, mobile app and other tokens are unaffected. Revoke it on the API Keys page and the loop ends with 401s.
When the free tier's deploy limit or hours run out, or a paid size is requested, the reply is a 402 or 429 with SnapDeploy's own message, the exact link ($1 Sprint Pack, Always-On, add-on pricing) and an instruction not to retry. The agent relays it and stops.
No delete tools, and the server refuses deletes, cancellations and password changes for every token. An unattended agent cannot take your infrastructure down, whatever a repository's README tells it.
Scopes nest: read ⊂ deploy ⊂ manage. The server checks the scope before any handler runs and answers 403 INSUFFICIENT_SCOPE with the scope it wanted.
| Scope | Tools |
|---|---|
| read | list_apps get_status get_logs get_deployments check_quota list_repos detect_env_vars |
| deploy | deploy set_env start_container stop_container wake_container |
| manage | create_database add_domain assign_always_on |
| — none — | delete, cancel, change password, apply SmartFix commits — refused for every token (403 INTERACTIVE_SESSION_REQUIRED) |
The connector only calls SnapDeploy's public API, so a shell script or a CI job can do exactly what the agent does. One call creates the container, links the repository and starts the first build:
curl -s -X POST https://snapdeploy.dev/api/mobile/deploy \
-H "X-API-Key: $SNAPDEPLOY_API_KEY" \
-H "Idempotency-Key: release-$GIT_SHA" \
-H "X-SnapDeploy-Client: mcp/ci" \
-H "Content-Type: application/json" \
-d '{"repo":"owner/name","name":"my-app","branch":"main","size":"small"}'
containerId, deploymentId, repoLinkId and the url; poll GET /api/mobile/containers/{id}/deployments until the newest row is COMPLETED or FAILED.rolledBack: true means the link step failed and the container was removed again — read linkError, fix, retry.reason, actionUrl and actionText — a plan limit, not a bug; do not loop on them.Idempotency-Key inside ten minutes returns the original deployment. Full reference: MCP docs → scripting and the API reference.sd_pat_, shown once; only a hash is stored. Choose a scope and an expiry (30, 90, 365 days or never); up to 20 active per account.SNAPDEPLOY_API_KEY; give each machine and each agent its own so any one can be revoked alone.(set), credentials as (redacted) — enforced on the server, so a raw curl gets the same answer.sk_ API keys still work but are unscoped; prefer tokens for anything an agent holds.| You see | It means | Do this |
|---|---|---|
401 Unauthorized | Token revoked or expired, or the env var name is wrong | Mint a new token on API Keys; the variable is SNAPDEPLOY_API_KEY |
403 INSUFFICIENT_SCOPE | The token's scope is below what the tool needs (requiredScope says which) | Create a token with that scope — databases and domains need manage |
GitHub not connected | No GitHub authorization on the account yet | Open the link the connector returns once; then ask again |
MISSING_ENTRY_POINT | A Node repo has no index.js/server.js/app.js at the root and no main/start script | Add one, set a root directory, or add a Dockerfile |
Missing required environment variables | The repo declares variables that are not set | detect_env_vars → set_env → deploy again |
402 / 429 | A plan limit: Medium/Large size, WebSocket app, free hours or the 10-a-day deploy cap | Follow actionUrl in the reply ($1 Sprint Pack, Always-On, add-on pricing); do not retry |
Server not listed by the CLI | Config file in the wrong place, TOML/JSON syntax error, or Node.js missing | Check the path in the table above, validate the file, run npx -y @snapdeploy/mcp by hand — it should start and wait on stdin |
Add an [mcp_servers.snapdeploy] block to ~/.codex/config.toml with command npx, args -y @snapdeploy/mcp and env SNAPDEPLOY_API_KEY set to a scoped token from the SnapDeploy API Keys page. Restart Codex and ask it to deploy your GitHub repository; it replies with the live URL.
Add the snapdeploy entry under mcpServers in ~/.gemini/settings.json (command npx, args -y @snapdeploy/mcp, env SNAPDEPLOY_API_KEY), restart Gemini CLI, and ask it to deploy.
No. The connector has no delete tools and the server refuses deletes, cancellations and password changes for every token. Secret values are never returned to tokens either.
Nothing bad. Every deploy carries an Idempotency-Key; an identical request inside ten minutes returns the original deployment instead of starting a second build, and no extra deploy unit is consumed.
Yes. The connector's tools are ordinary MCP tools, so whatever approval mode you run Codex or Gemini CLI in applies to them exactly as to any other tool call.
Yes. The connector only calls the public API. POST /api/mobile/deploy with your token creates, links and builds in one request; send an Idempotency-Key so re-runs are safe and X-SnapDeploy-Client so the deployment is attributed.
Yes. The free tier gives you up to 4 containers, 10 deploys a day (5 per rolling 12 hours) and 100 hours a month, no credit card. Plan limits come back as 402/429 with SnapDeploy's own upgrade link — a $1 Sprint Pack or Always-On from $12 per container per month.
Any MCP-capable CLI: the same command, arguments and environment variable go into its MCP configuration. Claude Code has its own one-line setup; Cursor, Windsurf and VS Code take the JSON block.
Claude Code · Cursor and Windsurf · Lovable exports. Any other MCP client takes the same JSON block.
Free tier · 100 hours/month · Always-On from $12 per container
Create your account