mcp: v0.8.0 — expand to all 6 resource types + claim_resource helper (#1)

The MCP server is the agent's primary entry point into instanode — it
needs to expose every resource type and surface the response's claim CTA
so agents can convert users into paying customers.

Tools added (6 → 11):
  - create_cache       POST /cache/new (Redis)
  - create_nosql       POST /nosql/new (MongoDB)
  - create_queue       POST /queue/new (NATS JetStream)
  - create_storage     POST /storage/new (S3-compatible / DO Spaces)
  - claim_resource     pure local helper — turns an upgrade JWT into
                       https://instanode.dev/start?t=<jwt>

Every create_* tool now surfaces the response's note + upgrade fields
via appendUpgradeBlock() so the agent literally sees the claim CTA and
URL in the tool response.

Files:
  src/client.ts   — 4 new endpoint methods + ProvisionResultBase typing
  src/index.ts    — 5 new tools registered + shared helpers
  package.json    — version 0.7.3 → 0.8.0, keywords expanded
  README.md       — tools table rewritten, claim flow explained
  test.sh         — expected-tools set updated to 11

Test gate: npm run build clean, npm test 6/6 pass against the live API
at https://api.instanode.dev.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mastermanas805

README.md

@@ -1,14 +1,26 @@
 # @instanode/mcp
 
 MCP server for [instanode.dev](https://instanode.dev). Lets AI coding agents
-(Claude Code, Cursor, Windsurf, Continue, etc.) provision ephemeral Postgres
-databases and webhook receivers over HTTPS — no Docker, no signup required
-for the free tier.
-
-- One tool call → one `postgres://` URL, usable immediately as `DATABASE_URL`.
-- pgvector is pre-installed on every database.
-- Free tier: 10 MB / 2 conn / 24h TTL. Paid (optional): 500 MB / 5 conn /
-  permanent, unlocked by setting `INSTANODE_TOKEN`.
+(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
+
+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
 
@@ -18,7 +30,7 @@ for the free tier.
 claude mcp add instanode -- npx -y @instanode/mcp@latest
 ```
 
-To authenticate (unlock paid tier, `list_resources`, `delete_resource`):
+To authenticate (unlock paid-tier limits and the account-management tools):
 
 ```bash
 claude mcp add instanode \
@@ -80,21 +92,44 @@ to reach for this MCP, see <https://instanode.dev/agent.html>.
 
 ## Environment
 
-| Variable            | Required | Default                        | Purpose                                                                                                     |
-|---------------------|----------|--------------------------------|-------------------------------------------------------------------------------------------------------------|
-| `INSTANODE_TOKEN`   | No       | —                              | Bearer JWT minted at <https://instanode.dev/dashboard>. Required for `list_resources`, `claim_token`, `delete_resource`, `get_api_token`. Unlocks paid-tier limits on `create_*`. |
-| `INSTANODE_API_URL` | No       | `https://api.instanode.dev`    | Override the API base URL. Only set this for local development.                                             |
+| Variable                  | Required | Default                       | Purpose                                                                                                                                                                                  |
+|---------------------------|----------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `INSTANODE_TOKEN`         | No       | —                             | Bearer JWT minted at <https://instanode.dev/dashboard>. Required for `list_resources`, `claim_token`, `delete_resource`, and `get_api_token`. Unlocks paid-tier limits on every `create_*`. |
+| `INSTANODE_API_URL`       | No       | `https://api.instanode.dev`   | Override the API base URL. Only set this for local development against a k3s cluster.                                                                                                    |
+| `INSTANODE_DASHBOARD_URL` | No       | `https://instanode.dev`       | Override the dashboard host that `claim_resource` builds claim URLs against. Only set this for staging.                                                                                  |
 
 ## Tools
 
-| Tool              | Description                                                                                       |
-|-------------------|---------------------------------------------------------------------------------------------------|
-| `create_postgres` | Provision a Postgres database (pgvector included). Returns a `postgres://` URL. `name` required.  |
-| `create_webhook`  | Provision an inbound webhook receiver URL. `name` required.                                       |
-| `list_resources`  | List resources on the caller's account. Requires `INSTANODE_TOKEN`.                               |
-| `claim_token`     | Attach an anonymous token to the authenticated account. Requires `INSTANODE_TOKEN`.               |
-| `delete_resource` | Hard-delete a resource you own. Paid tier only. Requires `INSTANODE_TOKEN`.                       |
-| `get_api_token`   | Mint a fresh 30-day bearer JWT (for rotation). Requires an existing `INSTANODE_TOKEN`.            |
+| Tool              | Description                                                                                                                                                       |
+|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `create_postgres` | `POST /db/new` — Provision a Postgres database (pgvector included). Returns `connection_url` + the `note`/`upgrade` claim URL. `name` required.                   |
+| `create_cache`    | `POST /cache/new` — Provision a Redis cache (ACL-scoped user + namespace). Returns `connection_url` + `note`/`upgrade`. `name` required.                          |
+| `create_nosql`    | `POST /nosql/new` — Provision a MongoDB database (per-resource user + DB-scoped role). Returns `connection_url` + `note`/`upgrade`. `name` required.              |
+| `create_queue`    | `POST /queue/new` — Provision a NATS JetStream queue (scoped subject namespace). Returns `connection_url` + `note`/`upgrade`. `name` required.                    |
+| `create_storage`  | `POST /storage/new` — Provision an S3-compatible bucket prefix (DigitalOcean Spaces). Returns endpoint, access keys, prefix + `note`/`upgrade`. `name` required.  |
+| `create_webhook`  | `POST /webhook/new` — Provision an inbound webhook receiver URL. Returns `receive_url` + `note`/`upgrade`. `name` required.                                       |
+| `claim_resource`  | Helper — turn an `upgrade_jwt` from any `create_*` response into the dashboard claim URL the user should click. No API call. No auth required.                    |
+| `claim_token`     | `POST /api/me/claim` — Programmatic claim: attach an anonymous resource to the authenticated account by its UUID `token`. Requires `INSTANODE_TOKEN`.             |
+| `list_resources`  | `GET /api/me/resources` — List resources on the caller's account. Requires `INSTANODE_TOKEN`.                                                                     |
+| `delete_resource` | `DELETE /api/me/resources/{token}` — Hard-delete a resource you own. Paid tier only. Requires `INSTANODE_TOKEN`.                                                  |
+| `get_api_token`   | `GET /api/me/token` — Mint a fresh 30-day bearer JWT (for rotation). Requires an existing `INSTANODE_TOKEN`.                                                      |
+
+### 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
 
@@ -104,12 +139,22 @@ to reach for this MCP, see <https://instanode.dev/agent.html>.
 >
 > **Claude:** *calls* `create_postgres({ name: "my-side-project" })`
 >
-> Returns a `connection_url` like `postgres://usr_a1b2:...@pg.instanode.dev:5432/db_a1b2?sslmode=require`.
+> 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 your migrations.
+> `.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`.
 
-### 2. "Set up a webhook to catch Stripe events"
+### 3. "Set up a webhook to catch Stripe events"
 
 > **You:** Give me a webhook URL I can point Stripe at.
 >
@@ -118,18 +163,33 @@ to reach for this MCP, see <https://instanode.dev/agent.html>.
 > Returns a `receive_url` that captures every request. `curl $receive_url`
 > pulls back the stored log.
 
-### 3. "Make last night's database permanent"
+### 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:** *(with `INSTANODE_TOKEN` set)* *calls*
-> `claim_token({ token: "a1b2c3d4-..." })` → resource is now linked to your
-> account with `tier=paid` and no expiry.
+> **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 free tier works without any setup. To unlock permanent resources, paid
-limits, and the `list_resources` / `delete_resource` tools:
+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.
@@ -143,8 +203,9 @@ Rotate any time by calling `get_api_token`, which mints a fresh 30-day JWT.
 ```bash
 npm install
 npm run build
-# Integration test (optional — requires a running instanode.dev server):
-INSTANODE_API_URL=http://localhost:30080 npm test
+# 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

package.json

@@ -1,14 +1,20 @@
 {
   "name": "@instanode/mcp",
-  "version": "0.7.3",
-  "description": "MCP server for instanode.dev \u2014 lets AI coding agents provision ephemeral Postgres databases and webhook receivers over HTTPS, with optional bearer-token auth for paid users.",
+  "version": "0.8.0",
+  "description": "MCP server for instanode.dev \u2014 lets AI coding agents provision ephemeral Postgres, Redis, MongoDB, NATS queues, S3-compatible object storage, and webhook receivers over HTTPS, with optional bearer-token auth for paid users.",
   "keywords": [
     "mcp",
     "claude",
     "cursor",
     "windsurf",
     "instanode.dev",
     "postgres",
+    "redis",
+    "mongodb",
+    "nats",
+    "s3",
+    "object-storage",
+    "webhook",
     "provisioning",
     "ai-agent",
     "database"

src/client.ts

@@ -8,9 +8,20 @@
  * Bearer auth is read from INSTANODE_TOKEN on every call so the user can
  * rotate the token without restarting the MCP process. Anonymous callers
  * simply leave the env var unset.
+ *
+ * Today's API surface (all live):
+ *   POST /db/new       — Postgres
+ *   POST /cache/new    — Redis
+ *   POST /nosql/new    — MongoDB
+ *   POST /queue/new    — NATS JetStream
+ *   POST /storage/new  — S3-compatible bucket
+ *   POST /webhook/new  — Webhook receiver
+ *   GET  /api/me/resources, POST /api/me/claim, DELETE /api/me/resources/{token}
+ *   GET  /api/me/token
  */
 
 const DEFAULT_BASE_URL = "https://api.instanode.dev";
+const DEFAULT_DASHBOARD_URL = "https://instanode.dev";
 
 export interface ClientOptions {
   baseURL?: string;
@@ -35,26 +46,60 @@ export interface ProvisionLimits {
   [key: string]: unknown;
 }
 
-export interface DatabaseProvisionResult {
+/**
+ * Shared fields every /<resource>/new response carries. Some resources have
+ * type-specific extras (receive_url for webhook, endpoint/access_key_id/etc
+ * for storage).
+ */
+export interface ProvisionResultBase {
   ok: boolean;
   id: string;
   token: string;
   name?: string;
-  connection_url: string;
   tier: string;
-  limits: ProvisionLimits;
+  limits?: ProvisionLimits;
+  /** Human-readable CTA the agent should surface verbatim. */
   note?: string;
+  /** https://instanode.dev/start?t=<jwt> — the dashboard claim URL. */
+  upgrade?: string;
+  /** Raw upgrade JWT (for callers that want to build their own claim URL). */
+  upgrade_jwt?: string;
+  expires_at?: string | null;
+  env?: string;
 }
 
-export interface WebhookProvisionResult {
-  ok: boolean;
-  id: string;
-  token: string;
-  name?: string;
+export interface DatabaseProvisionResult extends ProvisionResultBase {
+  /** postgres://... connection string, drop-in DATABASE_URL. */
+  connection_url: string;
+}
+
+export interface CacheProvisionResult extends ProvisionResultBase {
+  /** redis://user:pass@host:port — drop-in REDIS_URL. */
+  connection_url: string;
+}
+
+export interface NoSQLProvisionResult extends ProvisionResultBase {
+  /** mongodb://user:pass@host:port/db — drop-in MONGODB_URI. */
+  connection_url: string;
+}
+
+export interface QueueProvisionResult extends ProvisionResultBase {
+  /** nats://user:pass@host:port — drop-in NATS_URL. JetStream enabled. */
+  connection_url: string;
+}
+
+export interface StorageProvisionResult extends ProvisionResultBase {
+  /** Public bucket URL prefix, e.g. https://nyc3.digitaloceanspaces.com/instant-shared/<prefix>/ */
+  connection_url: string;
+  endpoint: string;
+  access_key_id: string;
+  secret_access_key: string;
+  prefix: string;
+}
+
+export interface WebhookProvisionResult extends ProvisionResultBase {
+  /** Public URL: POST anything to it, GET it to retrieve the captured log. */
   receive_url: string;
-  tier: string;
-  limits: ProvisionLimits;
-  note?: string;
 }
 
 export interface ClaimResult {
@@ -120,6 +165,18 @@ export class InstantClient {
     ).replace(/\/$/, "");
   }
 
+  /**
+   * Public dashboard URL — where the agent should direct the user to claim an
+   * anonymous resource. Reads INSTANODE_DASHBOARD_URL on every call so the user
+   * can override for staging without restarting the MCP process.
+   */
+  dashboardURL(): string {
+    return (process.env["INSTANODE_DASHBOARD_URL"] ?? DEFAULT_DASHBOARD_URL).replace(
+      /\/$/,
+      ""
+    );
+  }
+
   /** Read the bearer token fresh from the environment on every call. */
   private bearerToken(): string | undefined {
     const tok = process.env["INSTANODE_TOKEN"];
@@ -129,7 +186,7 @@ export class InstantClient {
   private headers(): Record<string, string> {
     const h: Record<string, string> = {
       "Content-Type": "application/json",
-      "User-Agent": "instanode-mcp/0.7.0",
+      "User-Agent": "instanode-mcp/0.8.0",
     };
     const tok = this.bearerToken();
     if (tok) {
@@ -197,6 +254,26 @@ export class InstantClient {
     return this.request<DatabaseProvisionResult>("POST", "/db/new", { name });
   }
 
+  /** POST /cache/new — provision a Redis cache. `name` is required. */
+  async createCache(name: string): Promise<CacheProvisionResult> {
+    return this.request<CacheProvisionResult>("POST", "/cache/new", { name });
+  }
+
+  /** POST /nosql/new — provision a MongoDB database. `name` is required. */
+  async createNoSQL(name: string): Promise<NoSQLProvisionResult> {
+    return this.request<NoSQLProvisionResult>("POST", "/nosql/new", { name });
+  }
+
+  /** POST /queue/new — provision a NATS JetStream queue. `name` is required. */
+  async createQueue(name: string): Promise<QueueProvisionResult> {
+    return this.request<QueueProvisionResult>("POST", "/queue/new", { name });
+  }
+
+  /** POST /storage/new — provision an S3-compatible object storage bucket prefix. `name` is required. */
+  async createStorage(name: string): Promise<StorageProvisionResult> {
+    return this.request<StorageProvisionResult>("POST", "/storage/new", { name });
+  }
+
   /** POST /webhook/new — provision a webhook receiver. `name` is required. */
   async createWebhook(name: string): Promise<WebhookProvisionResult> {
     return this.request<WebhookProvisionResult>("POST", "/webhook/new", { name });