InstaNode-dev

instanode-mcp

适用于 instanode.dev 的 MCP 服务。让 AI 编码 Agent（Claude Code、Cursor、Windsurf、Continue 等）通过 HTTPS 配置完整的临时开发基础设施套件——无需 Docker，免费匿名套餐无需注册。

每种资源类型只需调用一次工具，即可获取可直接使用的连接字符串：

• Postgres（create_postgres）→ postgres://...，已预装 pgvector
• Redis（create_cache）→ redis://...，带有 ACL 限定的用户和命名空间
• MongoDB（create_nosql）→ mongodb://...，角色权限限定在对应数据库
• NATS JetStream（create_queue）→ nats://...，带有范围限定的主题命名空间
• 兼容 S3 的存储（create_storage）→ 端点 + 密钥 + 前缀 （由 DigitalOcean Spaces 提供支持）
• Webhook 接收器（create_webhook）→ 存储每个入站请求的公开 URL
• 容器部署（create_deploy）→ 上传 base64 gzip tarball （Dockerfile + 源码），约 30 秒后即可获取公开 URL。通过 resource_bindings 传入上述资源的令牌，即可绑定这些资源——API 会在服务端将令牌解析为连接 URL。
• 多服务堆栈（create_stack）→ 在 instant.yaml 清单中声明 1..N 个服务， 并通过一次 MCP 调用将其作为套件部署。匿名调用者可获得 TTL 为 6 小时的堆栈， 并拥有 *.deployment.instanode.dev 下的实时 URL——无需信用卡。跨服务引用 （service://<name>）会在部署时于集群内部解析。使用 get_stack 查询 状态。

每个匿名资源都会在 24 小时后自动过期。资源配置响应会包含 note 和 upgrade 字段——MCP 服务会原样呈现这两个字段，让 Agent 向用户展示准确的行动号召和认领 URL，以便永久保留该 资源。对返回的 upgrade_jwt 调用 claim_resource，即可获取仪表板认领 URL。

安装

Claude Code

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

进行身份验证（解锁付费套餐的限额和账户管理工具）：

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

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

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

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

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

Continue.dev

添加到你的 ~/.continue/config.yaml：

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

如需可直接使用的 CLAUDE.md / .cursorrules，以告知 Agent 何时应调用此 MCP，请参阅 https://instanode.dev/agent.html。

环境变量

变量	必需	默认值	用途
INSTANODE_TOKEN	否	—	在 https://instanode.dev/dashboard 签发的 Bearer JWT。list_resources、claim_token、delete_resource、get_api_token 以及所有部署工具（create_deploy、list_deployments、get_deployment、redeploy、delete_deployment）均需要此令牌。为每个 create_* 解锁付费套餐限额。
INSTANODE_API_URL	否	https://api.instanode.dev	覆盖 API 基础 URL。仅在针对 k3s 集群进行本地开发时设置。
INSTANODE_DASHBOARD_URL	否	https://instanode.dev	覆盖 claim_resource 用于构建认领 URL 的仪表板主机。仅在预发布环境中设置。

工具

工具	描述
create_postgres	POST /db/new — 配置一个 Postgres 数据库（包含 pgvector）。返回 connection_url + note/upgrade 领取 URL。必须提供 name。
create_vector	POST /vector/new — 配置一个启用了 pgvector 的 Postgres 数据库（嵌入存储）。返回 connection_url + extension/dimensions + note/upgrade。必须提供 name；可选的 dimensions 是文档提示。
create_cache	POST /cache/new — 配置一个 Redis 缓存（限定 ACL 范围的用户 + 命名空间）。返回 connection_url + note/upgrade。必须提供 name。
create_nosql	POST /nosql/new — 配置一个 MongoDB 数据库（每个资源单独的用户 + 限定数据库范围的角色）。返回 connection_url + note/upgrade。必须提供 name。
create_queue	POST /queue/new — 配置一个 NATS JetStream 队列（限定范围的主题命名空间）。返回 connection_url + note/upgrade。必须提供 name。
create_storage	POST /storage/new — 配置一个兼容 S3 的存储桶前缀（DigitalOcean Spaces）。返回端点、访问密钥、前缀 + note/upgrade。必须提供 name。
create_webhook	POST /webhook/new — 配置一个入站 webhook 接收器 URL。返回 receive_url + note/upgrade。必须提供 name。
create_deploy	POST /deploy/new — 上传一个 base64 gzip tarball（包含 Dockerfile）并部署容器。返回 deploy_id、status、url、build_logs_url。必须提供 name。传入 redeploy: true（并使用相同的 name）可原地更新现有部署（相同的 app_id + URL）。需要 INSTANODE_TOKEN。
create_stack	POST /stacks/new — 多服务组合包。上传一个 instant.yaml 清单以及每个服务对应的一个 base64 gzip tarball；返回 stack_id、各服务 URL，以及匿名层级上的 6h-TTL 领取区块。适用于匿名用户（核心优势）。必须提供 name、manifest、service_tarballs。
get_stack	GET /stacks/{stack_id} — 轮询堆栈中各服务的状态和 URL。适用于匿名用户。必须提供 stack_id。
list_deployments	GET /api/v1/deployments — 列出调用者团队的所有部署。需要 INSTANODE_TOKEN。
get_deployment	GET /api/v1/deployments/:id — 获取一个部署（轮询，直到 status="running"）。需要 INSTANODE_TOKEN。
get_deployment_events	GET /api/v1/deployments/:id/events — 读取部署的故障时间线剖析（包含 kind/reason/exit_code/event/last_lines/hint/created_at，按时间从新到旧排列），以便 Agent 自行修复有问题的 Dockerfile。limit 为可选参数。需要 INSTANODE_TOKEN。
redeploy	POST /deploy/:id/redeploy — 按 ID 将更新后的代码推送到现有部署。URL 不变，重新构建。必须提供 tarball_base64（格式与 create_deploy 相同）——API 不会复用原始 tarball。对于更常见的“按名称更新”场景，建议使用 create_deploy({ name, redeploy: true, tarball_base64 })。需要 INSTANODE_TOKEN。
delete_deployment	DELETE /deploy/:id — 拆除正在运行的部署。此操作不可逆。需要 INSTANODE_TOKEN。
claim_resource	辅助工具 — 将任意 create_* 响应中的 upgrade_jwt 转换为用户应点击的控制面板领取 URL。不会发起 API 调用。无需身份验证。
claim_token	POST /claim — 程序化领取：使用资源的 upgrade_jwt + email，将匿名资源关联到已通过身份验证的账户。无需身份验证。
list_resources	GET /api/v1/resources — 列出调用者账户上的资源。需要 INSTANODE_TOKEN。
delete_resource	DELETE /api/v1/resources/{token} — 永久删除自己拥有的资源。仅限付费层级。需要 INSTANODE_TOKEN。
get_api_token	POST /api/v1/auth/api-keys — 创建一个新的 bearer Personal Access Token（PAT）。需要现有的用户会话 INSTANODE_TOKEN（PAT 不能创建其他 PAT——在这种情况下，API 会返回 403）。
get_capabilities	GET /api/v1/capabilities — 按升级顺序读取实时的各层级能力矩阵（存储 / 连接 / 资源数量 / 部署上限、定价、备份 + RPO/RTO 承诺），以便 Agent 在调用返回 402 前规划资源配置。身份验证可选（公开发现接口）。
set_vault_key	PUT /api/v1/vault/{env}/{key} — 将机密写入团队密钥库（始终创建新版本）。在部署的 env_vars 中通过 vault://{env}/{key} 引用；API 会在部署时解密。密钥库为付费功能（Hobby+ = 20 个条目，Pro/Team = 不限；Hobby/Pro 将 env 限定为 production）。需要 INSTANODE_TOKEN。
rotate_vault_key	POST /api/v1/vault/{env}/{key}/rotate — 轮换密钥库机密的值（创建新版本，并记录为独立的审计操作）。重新部署引用该机密的应用以应用更改。需要 INSTANODE_TOKEN。
update_deploy_env	PATCH /deploy/{id}/env — 将环境变量合并到现有部署中（传入值优先；值可以是 vault://env/KEY 引用）。返回合并后的映射，机密会被隐藏。重新部署以应用更改。需要 INSTANODE_TOKEN。
update_stack_env	PATCH /stacks/{slug}/env — 将环境变量合并到现有堆栈中（对行加锁；空字符串值会删除键）。重新部署堆栈以应用更改。需要 INSTANODE_TOKEN。
presign_storage	POST /storage/{token}/presign — 创建一个有时效限制（≤1h）的预签名 S3 URL（GET/PUT/HEAD），其访问范围限定为一个存储前缀。通过路径中的存储令牌进行身份验证——匿名层级的存储也可使用。未提供 DELETE（泄露的 URL 不得清空前缀）。
pause_resource	POST /api/v1/resources/{id}/pause — 暂停资源但不删除（保留存储 + 连接 URL；拒绝新连接）。**Pro 层级及以上可用。**需要 INSTANODE_TOKEN。
resume_resource	POST /api/v1/resources/{id}/resume — 恢复已暂停的资源（相同的连接 URL 仍可使用）。**Pro 层级及以上可用。**需要 INSTANODE_TOKEN。
rotate_credentials	POST /api/v1/resources/{id}/rotate-credentials — 轮换资源密码；以明文返回新的 connection_url（主机 + 数据库不变）。使泄露的旧 URL 失效。需要 INSTANODE_TOKEN。
wake_deployment	POST /deploy/{id}/wake — 显式唤醒已缩容至零的部署（扩容至 1 个副本；启动后才开始提供服务）。此功能受平台标志控制：功能关闭时返回 501 scale_to_zero_disabled。需要 INSTANODE_TOKEN。

容器部署（create_deploy）

部署只需发送一个 multipart/form-data POST 请求，其中包含项目的 base64 编码 gzip tarball（Dockerfile + 源代码）。MCP 工具会处理编码相关的流程；Agent 只需构建 tarball。

构建 tarball（任意语言）：

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");

上限：解码后 50 MB。遵循 .dockerignore——只打包 docker build 所需的内容。必须提供 name 字段（1–64 个字符，包含字母、数字、空格或连字符）——这是仪表板上显示的易读标签。

绑定已配置的资源：

先使用 create_postgres / create_cache / 等工具配置资源，以获取其令牌（UUID），然后将令牌作为 resource_bindings 传入：

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

Agent 传入的是资源令牌（而非连接 URL）；API 会在部署时于服务端将每个令牌解析为其连接 URL。MCP 服务不会预先解析令牌——预先解析会让每个绑定都经过 GET /credentials 往返，并将原始密钥嵌入工具参数，而 Agent 宿主可能会记录这些参数。

轮询：

create_deploy 会立即返回 status="building"。每隔几秒轮询一次 get_deployment({ id: deploy_id })，直到状态变为 "running"（通常约 30 秒）。此时，url 字段就是可访问的 URL。

更新现有部署（URL 不变，使用新构建）

要发布已部署应用的 v2 版本，同时不更改 URL 或 app_id，请再次调用 create_deploy，并使用相同的 name，同时设置 redeploy: true：

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

api 会根据 (team_id, name) 查找现有部署，并就地更新——app_id 不变，*.deployment.instanode.dev URL 不变；新镜像部署期间，状态会变回 building。

如果不设置 redeploy: true，使用之前用过的名称调用 create_deploy 会生成一个新的 app_id 和一个新的 URL（旧行为）。这正是导致 AGENT-UX 问题的原因：Agent 最终为同一个应用创建了两个正在运行的部署和两个 URL。

独立的 redeploy 工具（按 id 而非 name）仍可使用，并且也需要 tarball_base64——api 不会重用原始 tarball。如果你知道名称，优先使用 create_deploy({ name, redeploy: true })；如果你只有部署 ID，则使用 redeploy({ id, tarball_base64 })。

私有部署

设置 private: true 并传入 allowed_ips，即可在 Ingress 限制特定 IP 或 CIDR 网段的访问。当 Agent 被要求部署 CRM、内部仪表板或仅应对用户开放的预发布应用时，这项功能很有用。

需要 Pro 套餐或更高等级。 Hobby 套餐调用者会收到 HTTP 402 响应，其中包含 agent_action 字段——MCP 服务会提供升级 URL，供 Agent 提示用户升级。

提示词示例（粘贴到 Claude Code 中）：

“将我的 CRM 部署为私有应用，只允许从 1.2.3.4 和我的办公室子网 10.0.0.0/8 访问。”

接下来，Agent 会调用：

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

get_deployment 和 list_deployments 会向 Agent 提供 private 和 allowed_ips，以便向用户确认访问策略。要将私有部署改为公开部署，请在重新部署时不带这些标志。

匿名资源如何转为已认领资源

每个 create_* 工具都会返回三个字段，Agent 应将它们视为关键字段：

• token — 资源 UUID（用于 claim_token 和 delete_resource）。
• note — 一句易读的 CTA，已包含升级 URL。
• upgrade — 完整的认领 URL（https://instanode.dev/start?t=<jwt>）。用户点击后，通过 GitHub / Google 登录或使用魔法链接登录，资源随后会关联到其账户。

还会返回 upgrade_jwt，供希望围绕认领流程构建自定义 UI 的调用者使用。claim_resource 工具接受该 JWT，并返回相同的仪表板 URL——如果 Agent 想在对话中重新提供认领 URL（例如，原始响应已滚出上下文），这会很有用。

Agent 交互示例

1. “这个项目需要一个 Postgres”

你： Claude，这个项目需要一个 Postgres 数据库。

Claude： 调用 create_postgres({ name: "my-side-project" })

返回类似 postgres://usr_a1b2:[email protected]:5432/db_a1b2?sslmode=require 的 connection_url， 以及 note: "Works for 24h free. Claim to keep — from $9/mo: https://instanode.dev/start?t=..."。

Claude 接着： 将 DATABASE_URL=... 写入 .env，将 .env 添加到 .gitignore，运行迁移，并原样向用户显示认领 URL， 让用户知道如何让数据库保留超过 24h。

2. “启动一个 Redis 缓存来进行速率限制”

你： 添加一个 Redis 缓存，这样我就能限制 API 的请求速率。

Claude： 调用 create_cache({ name: "api-ratelimit" })

返回类似 redis://usr_b2c3:[email protected]:6379/0 的 connection_url。

3. “设置一个 webhook 来接收 Stripe 事件”

你： 给我一个可以填到 Stripe 中的 webhook URL。

Claude： 调用 create_webhook({ name: "stripe-sandbox" })

返回一个可以捕获每个请求的 receive_url。运行 curl $receive_url 会返回存储的日志。

4. “为用户上传内容提供对象存储”

你： 我需要兼容 S3 的存储来上传头像。

Claude： 调用 create_storage({ name: "user-avatars" })

返回 endpoint、access key、secret key 和 prefix。Claude 使用返回的凭据配置 AWS SDK。

5. “让昨晚创建的数据库永久保留”

你： 我想让你昨天创建的数据库保留超过 24h。

Claude（未设置 INSTANODE_TOKEN）： 调用 claim_resource({ upgrade_jwt: "<the upgrade_jwt from yesterday's response>" }) → 向你显示控制面板认领 URL。你点击该链接并登录，资源便会关联到你的账户。

Claude（已设置 INSTANODE_TOKEN）： 调用 claim_token({ token: "a1b2c3d4-..." }) → 资源现在已关联到经过身份验证的账户， 无需通过浏览器跳转。

身份验证

匿名套餐无需任何设置即可使用。若要解锁付费额度、永久资源和账户管理工具（list_resources、 delete_resource、claim_token、get_api_token）：

1. 使用 GitHub 在 https://instanode.dev 注册。
2. 前往控制面板并复制 bearer token。
3. 将其设为 MCP 服务 env 块中的 INSTANODE_TOKEN（参见上方示例）。

随时调用 get_api_token 进行轮换，该工具会通过 POST /api/v1/auth/api-keys 签发新的 Personal Access Token。PAT 基于撤销机制（不受时间限制）。注意：PAT 无法签发其他 PAT——get_api_token 需要用户会话 token（通过控制面板登录获取），而非现有 PAT，否则 API 会返回 403。

开发

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

许可证

MIT — (c) instanode.dev