instanode-mcp

MCP server for instanode.dev. Lets AI coding agents (Claude Code, Cursor, Windsurf, Continue, etc.) provision the full bundle of ephemeral developer infrastructure over HTTPS — no Docker, no signup required for the free anonymous tier.

One tool call per resource type, each returning a drop-in connection string:

• Postgres (create_postgres) → postgres://... with pgvector pre-installed
• Redis (create_cache) → redis://... with ACL-scoped user + namespace
• MongoDB (create_nosql) → mongodb://... with role scoped to the DB
• NATS JetStream (create_queue) → nats://... with scoped subject namespace
• S3-compatible storage (create_storage) → endpoint + keys + prefix (backed by DigitalOcean Spaces)
• Webhook receiver (create_webhook) → public URL that stores every inbound request
• Container deployment (create_deploy) → upload a base64 gzip tarball (Dockerfile + source), get back a public URL in ~30s. Bind any of the resources above by passing their tokens as resource_bindings — the API resolves tokens to connection URLs server-side.
• Multi-service stack (create_stack) → declare 1..N services in an instant.yaml manifest, ship them as a bundle in a single MCP call. Anonymous callers get a 6h-TTL stack with a live URL on *.deployment.instanode.dev — no card required. Cross-service refs (service://<name>) resolve cluster-internally at deploy time. Poll status with get_stack.

Every anonymous resource auto-expires in 24h. The provision response carries a note and upgrade field — the MCP server surfaces both verbatim so the agent can show the user the exact CTA + claim URL needed to keep the resource permanently. Run claim_resource on the returned upgrade_jwt to get the dashboard claim URL.

Install

Claude Code

claude mcp add instanode -- npx -y instanode-mcp@latest

To authenticate (unlock paid-tier limits and the account-management tools):

claude mcp add instanode \
  --env INSTANODE_TOKEN=<paste from https://instanode.dev/dashboard> \
  -- npx -y instanode-mcp@latest

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "instanode": {
      "command": "npx",
      "args": ["-y", "instanode-mcp@latest"],
      "env": {
        "INSTANODE_TOKEN": "<optional — paste from dashboard for paid tier>"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "instanode": {
      "command": "npx",
      "args": ["-y", "instanode-mcp@latest"],
      "env": {
        "INSTANODE_TOKEN": "<optional>"
      }
    }
  }
}

Continue.dev

Add to your ~/.continue/config.yaml:

mcpServers:
  - name: instanode
    command: npx
    args: ["-y", "instanode-mcp@latest"]
    env:
      INSTANODE_TOKEN: "<optional>"

For a drop-in CLAUDE.md / .cursorrules that tells the agent exactly when to reach for this MCP, see https://instanode.dev/agent.html.

Environment

Tools

Container deployment (create_deploy)

Deploying is a single multipart/form-data POST with a base64-encoded gzip tarball of the project (Dockerfile + source). The MCP tool handles the encoding plumbing; the agent's job is just to construct the tarball.

Building the tarball (any language):

import base64, subprocess
tar = subprocess.check_output(["tar", "czf", "-", "-C", project_dir, "."])
tarball_base64 = base64.b64encode(tar).decode()

import { execFileSync } from "node:child_process";
const tar = execFileSync("tar", ["czf", "-", "-C", projectDir, "."]);
const tarball_base64 = tar.toString("base64");

Cap: 50 MB after decode. Honor .dockerignore — only ship what docker build needs. The name field is required (1–64 chars, letters/numbers/spaces/dashes) — it's the human-readable label shown on the dashboard.

Binding provisioned resources:

Provision the resources first with create_postgres / create_cache / etc. to get their tokens (UUIDs), then pass the tokens as resource_bindings:

{
  "tarball_base64": "...",
  "name": "my-app",
  "port": 8080,
  "resource_bindings": {
    "DATABASE_URL": "<token from create_postgres>",
    "REDIS_URL":    "<token from create_cache>"
  }
}

The agent passes resource tokens (not connection URLs); the API resolves each token to its connection URL server-side at deploy time. The MCP server never pre-resolves tokens — pre-resolving would round-trip every binding through GET /credentials and embed raw secrets into the tool params, which the agent host may log.

Polling:

create_deploy returns status="building" immediately. Poll get_deployment({ id: deploy_id }) every few seconds until status flips to "running" (typical: ~30s). At that point the url field is the live URL.

Updating an existing deployment (same URL, new build)

To ship v2 of an app you already deployed without changing the URL or app_id, call create_deploy again with the same name plus redeploy: true:

{
  "tarball_base64": "...",
  "name": "my-app",
  "redeploy": true
}

The api finds the existing deployment by (team_id, name) and updates it in place — same app_id, same *.deployment.instanode.dev URL, status flips back to building while the new image rolls out.

Without redeploy: true, calling create_deploy with a name you've used before mints a new app_id and a new URL (the legacy behaviour). This is the trap that caused the AGENT-UX issue where agents ended up with two live deployments + two URLs for the same app.

The standalone redeploy tool (by id, not name) still works and also requires a tarball_base64 — the api never reuses the original tarball. Prefer the create_deploy({ name, redeploy: true }) path when you have the name; use redeploy({ id, tarball_base64 }) when you only have the deploy id.

Private deploys

Set private: true and pass allowed_ips to restrict access to specific IPs or CIDR blocks at the Ingress. Useful when the agent is asked to deploy a CRM, internal dashboard, or staging app that should only be reachable by the user.

Pro tier or higher required. Hobby callers will see HTTP 402 with an agent_action field — the MCP server surfaces the upgrade URL so the agent can prompt the user to upgrade.

Example prompt (paste into Claude Code):

"Deploy my CRM as a private app, only accessible from 1.2.3.4 and my office subnet 10.0.0.0/8"

The agent will then call:

{
  "tarball_base64": "...",
  "name": "my-crm",
  "private": true,
  "allowed_ips": ["1.2.3.4", "10.0.0.0/8"]
}

get_deployment and list_deployments surface private + allowed_ips back to the agent so it can confirm the policy to the user. To turn a private deploy public, redeploy without the flags.

How anonymous → claimed works

Every create_* tool returns three fields the agent should treat as load-bearing:

• token — the resource UUID (used for claim_token and delete_resource).
• note — a one-sentence human-readable CTA, already mentions the upgrade URL.
• upgrade — the full claim URL (https://instanode.dev/start?t=<jwt>). The user clicks it, signs in with GitHub/Google or a magic link, and the resource is attached to their account.

upgrade_jwt is also returned for callers that want to build their own UI around the claim flow. The claim_resource tool accepts that JWT and returns the same dashboard URL — useful if the agent wants to re-surface the claim URL later in the conversation after the original response has scrolled out of context.

Example agent interactions

1. "I need a Postgres for this project"

You: Claude, I need a Postgres database for this project.

Claude: calls create_postgres({ name: "my-side-project" })

Returns a connection_url like postgres://usr_a1b2:...@pg.instanode.dev:5432/db_a1b2?sslmode=require, plus note: "Works for 24h free. Claim to keep — from $9/mo: https://instanode.dev/start?t=...".

Claude then: writes DATABASE_URL=... to .env, adds .env to .gitignore, runs the migrations, and shows the user the claim URL verbatim so they know how to keep the database past 24h.

2. "Spin up a Redis cache for rate limiting"

You: Add a Redis cache so I can rate-limit my API.

Claude: calls create_cache({ name: "api-ratelimit" })

Returns a connection_url like redis://usr_b2c3:...@redis.instanode.dev:6379/0.

3. "Set up a webhook to catch Stripe events"

You: Give me a webhook URL I can point Stripe at.

Claude: calls create_webhook({ name: "stripe-sandbox" })

Returns a receive_url that captures every request. curl $receive_url pulls back the stored log.

4. "Object storage for user uploads"

You: I need S3-compatible storage for uploaded avatars.

Claude: calls create_storage({ name: "user-avatars" })

Returns endpoint, access key, secret key, and prefix. Claude wires the AWS SDK with the returned credentials.

5. "Make last night's database permanent"

You: I want to keep the database you made yesterday past 24h.

Claude (no INSTANODE_TOKEN): calls claim_resource({ upgrade_jwt: "<the upgrade_jwt from yesterday's response>" }) → shows you the dashboard claim URL. You click it, sign in, the resource is attached.

Claude (with INSTANODE_TOKEN): calls claim_token({ token: "a1b2c3d4-..." }) → resource is now linked to the authenticated account, no browser round-trip needed.

Authentication

The anonymous tier works without any setup. To unlock paid limits, permanent resources, and the account-management tools (list_resources, delete_resource, claim_token, get_api_token):

1. Sign up at https://instanode.dev with GitHub.
2. Visit the dashboard and copy your bearer token.
3. Set it as INSTANODE_TOKEN in the MCP server's env block (see examples above).

Rotate any time by calling get_api_token, which mints a fresh Personal Access Token via POST /api/v1/auth/api-keys. PATs are revocation-based (not time-bound). NOTE: PATs cannot mint other PATs — get_api_token requires a user-session token (sign in via the dashboard), not an existing PAT, otherwise the API returns 403.

Development

npm install
npm run build
# Integration test (optional — requires a running instanode.dev server.
# For local k8s, port-forward first: kubectl port-forward -n instant svc/instant-api 8080:8080):
INSTANODE_API_URL=http://localhost:8080 npm test

License

MIT — (c) instanode.dev