Merge pull request #5 from InstaNode-dev/feat/private-deploy-mcp-fresh

mcp: create_deploy gains private + allowed_ips for Pro-tier private deploys (v0.10.0)

Author: mastermanas805

README.md

@@ -175,6 +175,37 @@ params, which the agent host may log.
 `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.
 
+### 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:
+
+```json
+{
+  "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

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "instanode-mcp",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "MCP server for instanode.dev \u2014 lets AI coding agents provision ephemeral Postgres, Redis, MongoDB, NATS queues, S3-compatible object storage, webhook receivers, and deploy containerized apps over HTTPS, with optional bearer-token auth for paid users.",
   "keywords": [
     "mcp",

package.json

@@ -130,6 +130,21 @@ export interface Deployment {
   created_at?: string;
   updated_at?: string;
   team_id?: string;
+  /**
+   * Private deploy flag — when true, the deploy's Ingress only accepts traffic
+   * from `allowed_ips`. Pro tier or higher required (anonymous + hobby are 402).
+   */
+  private?: boolean;
+  /**
+   * IP / CIDR allowlist enforced at the Ingress when `private` is true.
+   * Strings like "1.2.3.4" or "10.0.0.0/8". Empty / undefined when
+   * `private` is false.
+   *
+   * Track A's backend contract uses `allowed_ips`. If Track A ends up renaming
+   * to `allowed_cidrs`, reconcile post-merge with a one-line schema rename
+   * (see PR body).
+   */
+  allowed_ips?: string[];
 }
 
 /**
@@ -200,6 +215,19 @@ export interface CreateDeployParams {
    * tool params, which the agent host may log.
    */
   resource_bindings?: Record<string, string>;
+  /**
+   * Private deploy flag. When true, the Ingress only accepts traffic from
+   * `allowed_ips`. Requires Pro tier or higher (api returns 402 on hobby
+   * with an `agent_action` upgrade prompt).
+   */
+  private?: boolean;
+  /**
+   * IP / CIDR allowlist (required when `private=true`). Strings like
+   * "1.2.3.4" or "10.0.0.0/8". The MCP client forwards this as-is to
+   * Track A's backend contract; if Track A ships with a slightly different
+   * shape (e.g. `allowed_cidrs`), reconcile post-merge.
+   */
+  allowed_ips?: string[];
 }
 
 export interface ClaimResult {
@@ -286,7 +314,7 @@ export class InstantClient {
   private headers(): Record<string, string> {
     const h: Record<string, string> = {
       "Content-Type": "application/json",
-      "User-Agent": "instanode-mcp/0.9.0",
+      "User-Agent": "instanode-mcp/0.10.0",
     };
     const tok = this.bearerToken();
     if (tok) {
@@ -301,7 +329,7 @@ export class InstantClient {
    */
   private authHeaders(): Record<string, string> {
     const h: Record<string, string> = {
-      "User-Agent": "instanode-mcp/0.9.0",
+      "User-Agent": "instanode-mcp/0.10.0",
     };
     const tok = this.bearerToken();
     if (tok) {
@@ -510,6 +538,17 @@ export class InstantClient {
     if (typeof params.port === "number") form.append("port", String(params.port));
     if (params.env) form.append("env", params.env);
 
+    // Private deploy + IP allowlist (Track A backend contract). Booleans and
+    // arrays go through multipart as strings — the api parses them back. We
+    // intentionally forward `private` even when false so the server can
+    // distinguish "explicitly public" from "field omitted".
+    if (typeof params.private === "boolean") {
+      form.append("private", params.private ? "true" : "false");
+    }
+    if (params.allowed_ips && params.allowed_ips.length > 0) {
+      form.append("allowed_ips", JSON.stringify(params.allowed_ips));
+    }
+
     // Merge resource_bindings into env_vars. The api treats every value
     // either as plaintext, a vault://env/KEY ref, or — for deploy bindings —
     // a raw resource token that the server resolves to a connection URL

src/client.ts

@@ -614,7 +614,9 @@ rotating an expiring token.`,
 
 server.tool(
   "create_deploy",
-  `Deploy a containerized application on instanode.dev (POST /deploy/new).
+  `Create a new deploy. Optionally set \`private: true\` + \`allowed_ips: ['1.2.3.4', '10.0.0.0/8']\` to restrict access to specific IPs. Requires Pro tier or higher. Useful when an agent is asked to deploy a CRM, internal dashboard, or staging app that should only be reachable by the user.
+
+Deploys a containerized application on instanode.dev (POST /deploy/new).
 
 The agent base64-encodes a gzip tarball of the user's project (must contain a
 Dockerfile at the root), passes it as 'tarball_base64', and the API builds +
@@ -642,6 +644,10 @@ vault is per-team, per-env; rotate without redeploying). 'env_vars' and
 'resource_bindings' are merged before being sent to the API; on collision,
 'resource_bindings' wins.
 
+Private deploys: set 'private: true' and pass 'allowed_ips' (IPs or CIDR
+blocks) to restrict access at the Ingress. Pro tier or higher is required —
+hobby tier returns 402 with an agent_action prompting the user to upgrade.
+
 Requires INSTANODE_TOKEN (anonymous tier cannot deploy).`,
   {
     tarball_base64: z
@@ -681,6 +687,18 @@ Requires INSTANODE_TOKEN (anonymous tier cannot deploy).`,
       .describe(
         "Map of env var name → resource token UUID (e.g. { DATABASE_URL: '<postgres token>' }). The API resolves each token to its connection URL server-side. DO NOT pass raw connection URLs here — use create_postgres/create_cache/etc. to get tokens, then bind them."
       ),
+    private: z
+      .boolean()
+      .optional()
+      .describe(
+        "When true, the deploy is only reachable from IPs in 'allowed_ips'. Requires Pro tier or higher — anonymous and hobby callers get HTTP 402 with an agent_action prompting the user to upgrade. Use for CRMs, internal dashboards, staging apps."
+      ),
+    allowed_ips: z
+      .array(z.string().min(1))
+      .optional()
+      .describe(
+        "IP / CIDR allowlist enforced at the Ingress when 'private' is true. Examples: ['1.2.3.4', '10.0.0.0/8', '203.0.113.42/32']. Required when private=true; ignored otherwise. If Track A's backend lands with a renamed field (e.g. 'allowed_cidrs'), this MCP tool will surface the 400 verbatim — see PR body."
+      ),
   },
   async (params) => {
     try {
@@ -694,6 +712,13 @@ Requires INSTANODE_TOKEN (anonymous tier cannot deploy).`,
           : `URL:            (pending — poll get_deployment until status="running")`,
         `Build logs:     ${result.build_logs_url}`,
       ];
+      if (result.item.private) {
+        lines.push(`Private:        true`);
+        const ips = result.item.allowed_ips ?? params.allowed_ips ?? [];
+        if (ips.length > 0) {
+          lines.push(`Allowed IPs:    ${ips.join(", ")}`);
+        }
+      }
       appendUpgradeBlock(lines, result);
       lines.push(
         ``,
@@ -736,6 +761,10 @@ Requires INSTANODE_TOKEN.`,
           `  port:   ${d.port}`,
         ];
         if (d.environment) parts.push(`  env:    ${d.environment}`);
+        if (d.private) {
+          const ips = d.allowed_ips && d.allowed_ips.length > 0 ? ` (${d.allowed_ips.join(", ")})` : "";
+          parts.push(`  private: true${ips}`);
+        }
         if (d.created_at) parts.push(`  created: ${d.created_at}`);
         if (d.error) parts.push(`  error:  ${d.error}`);
         return parts.join("\n");
@@ -778,6 +807,12 @@ Requires INSTANODE_TOKEN.`,
         `Port:        ${d.port}`,
       ];
       if (d.environment) lines.push(`Environment: ${d.environment}`);
+      if (d.private) {
+        lines.push(`Private:     true`);
+        if (d.allowed_ips && d.allowed_ips.length > 0) {
+          lines.push(`Allowed IPs: ${d.allowed_ips.join(", ")}`);
+        }
+      }
       if (d.error) lines.push(`Error:       ${d.error}`);
       if (d.created_at) lines.push(`Created:     ${d.created_at}`);
       if (d.updated_at) lines.push(`Updated:     ${d.updated_at}`);

src/index.ts

@@ -114,6 +114,47 @@ assert 'INSTANODE_TOKEN' in text, f'expected auth-required text, got: {text}'
 " || fail "create_deploy without token failed to surface auth message"
 pass "create_deploy without token returns auth-required message"
 
+# Test 5c: create_deploy schema accepts the new private + allowed_ips fields.
+# tools/list returns the JSON schema; check both fields are advertised.
+RESP=$(printf "%s\n%s\n" "$INIT" "$TOOLS_LIST" | INSTANODE_API_URL="$BASE_URL" $MCP 2>/dev/null | tail -1)
+echo "$RESP" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+tools = {t['name']: t for t in d['result']['tools']}
+schema = tools['create_deploy']['inputSchema']
+props = schema.get('properties', {})
+assert 'private' in props, f'create_deploy missing private property: {list(props.keys())}'
+assert 'allowed_ips' in props, f'create_deploy missing allowed_ips property: {list(props.keys())}'
+priv = props['private']
+priv_type = priv.get('type') or [t for t in priv.get('anyOf', []) if 'type' in t]
+assert priv_type in ('boolean', [{'type': 'boolean'}]) or priv.get('type') == 'boolean', f'private should be boolean, got: {priv}'
+ips = props['allowed_ips']
+assert ips.get('type') == 'array', f'allowed_ips should be an array, got: {ips}'
+desc = tools['create_deploy'].get('description', '')
+assert 'Pro tier' in desc or 'pro tier' in desc.lower(), f'create_deploy description missing tier-gate note'
+assert 'private' in desc.lower(), f'create_deploy description missing private note'
+" || fail "create_deploy schema missing private + allowed_ips properties"
+pass "create_deploy schema advertises private + allowed_ips with tier-gate note"
+
+# Test 5d: create_deploy with private=true + allowed_ips but no INSTANODE_TOKEN
+# should still pass schema validation and surface the auth-required message
+# (not a Zod validation error).
+DEPLOY_PRIVATE='{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"create_deploy","arguments":{"tarball_base64":"H4sIAAAAAAAA","name":"my-crm","private":true,"allowed_ips":["1.2.3.4","10.0.0.0/8"]}}}'
+RESP=$(printf "%s\n%s\n" "$INIT" "$DEPLOY_PRIVATE" | INSTANODE_API_URL="$BASE_URL" $MCP 2>/dev/null | tail -1)
+echo "$RESP" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+# Either auth-required text (no token set, schema accepted the input) or a
+# clean ApiError from the upstream — both prove the schema accepted private +
+# allowed_ips. A Zod validation error would come back as d['error'] or
+# isError=True with 'Invalid' in the text.
+assert 'error' not in d or not d['error'], f'unexpected JSON-RPC error: {d}'
+text = d['result']['content'][0]['text']
+# Must not be a Zod validation failure on the new fields.
+assert 'private' not in text or 'INSTANODE_TOKEN' in text or 'instanode.dev' in text.lower(), f'schema rejected private+allowed_ips: {text}'
+" || fail "create_deploy with private+allowed_ips was rejected at the schema layer"
+pass "create_deploy accepts private+allowed_ips (forwards through to api / auth gate)"
+
 # Test 6: claim_resource accepts a full /start?t= URL and re-extracts the JWT.
 CLAIM_URL='{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"claim_resource","arguments":{"upgrade_jwt":"https://instanode.dev/start?t=ey.url.jwt"}}}'
 RESP=$(printf "%s\n%s\n" "$INIT" "$CLAIM_URL" | INSTANODE_API_URL="$BASE_URL" $MCP 2>/dev/null | tail -1)