feat(cloud): add sandbox MCP server for local Claude Code access to remote sandboxes

Instead of using Claude Code inside the browser-based dev UI, users can now
interact with their cloud sandbox from local Claude Code via an MCP server
that proxies filesystem and bash operations over SSH.

New commands:
- `crayon mcp sandbox` — starts the sandbox MCP server (runs on cloud machine)
- `crayon cloud mcp [app-name]` — registers MCP server and launches local Claude Code

`crayon cloud run` now auto-registers the MCP server and drops users into
local Claude Code after the sandbox is ready (also opens the dev UI).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Askir

packages/core/src/cli/cloud-dev.ts

@@ -1,4 +1,4 @@
-import { execSync, spawnSync } from "node:child_process";
+import { execFileSync, execSync, spawnSync } from "node:child_process";
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, userInfo } from "node:os";
@@ -127,11 +127,25 @@ export async function runCloudRun(): Promise<void> {
       const existing = existingSandboxes.find((m) => m.app_name === choice);
       if (existing?.app_url) {
         const devUrl = existing.app_url.replace(/\/$/, "") + "/dev/";
-        p.log.info(`URL: ${pc.cyan(devUrl)}`);
-        openInBrowser(devUrl);
+        p.log.info(`Dev UI: ${pc.cyan(devUrl)}`);
       }
       p.log.info(`Status: ${pc.bold(existing?.fly_state ?? "unknown")}`);
-      p.outro(pc.green("Sandbox ready."));
+
+      // Open dev UI and register MCP + launch local Claude Code
+      if (existing?.app_url) openInBrowser(existing.app_url.replace(/\/$/, "") + "/dev/");
+
+      const s = p.spinner();
+      s.start("Registering sandbox MCP server...");
+      const ok = await registerSandboxMcp(choice as string);
+      if (ok) {
+        s.stop(pc.green("MCP server registered"));
+        p.log.info("Launching Claude Code with sandbox access...");
+        p.outro("");
+        launchClaude();
+      } else {
+        s.stop(pc.yellow("MCP registration failed"));
+        p.outro(pc.green("Sandbox ready."));
+      }
       return;
     }
 
@@ -235,9 +249,21 @@ export async function runCloudRun(): Promise<void> {
           const baseUrl = statusResult.url ?? createResult.appUrl;
           const devUrl = baseUrl.replace(/\/$/, "") + "/dev/";
           s.stop(pc.green("Sandbox is running!"));
-          p.log.info(`URL: ${pc.cyan(devUrl)}`);
+          p.log.info(`Dev UI: ${pc.cyan(devUrl)}`);
           openInBrowser(devUrl);
-          p.outro(pc.green("Cloud dev environment is ready!"));
+
+          // Register MCP and launch local Claude Code
+          s.start("Registering sandbox MCP server...");
+          const ok = await registerSandboxMcp(appName as string);
+          if (ok) {
+            s.stop(pc.green("MCP server registered"));
+            p.log.info("Launching Claude Code with sandbox access...");
+            p.outro("");
+            launchClaude();
+          } else {
+            s.stop(pc.yellow("MCP registration failed"));
+            p.outro(pc.green("Cloud dev environment is ready!"));
+          }
           return;
         }
 
@@ -515,6 +541,86 @@ export async function handleClaude(extraArgs: string[] = []): Promise<void> {
   process.exit(exitCode);
 }
 
+// ── MCP sandbox registration ────────────────────────────────
+
+const MCP_SERVER_NAME = "crayon-sandbox";
+
+async function registerSandboxMcp(appName: string): Promise<boolean> {
+  let sshInfo: SSHKeyInfo;
+  try {
+    sshInfo = await getSSHKey(appName);
+  } catch (err) {
+    p.log.error(
+      `Failed to get SSH key: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+
+  // Ensure key is cached on disk (getSSHKey already does this)
+  const keyPath = getCachedKeyPath(appName);
+
+  const sshArgs = [
+    "-i", keyPath,
+    "-p", String(sshInfo.port),
+    "-o", "StrictHostKeyChecking=no",
+    "-o", "UserKnownHostsFile=/dev/null",
+    "-o", "LogLevel=ERROR",
+    "-o", "IdentitiesOnly=yes",
+    `${sshInfo.linuxUser}@${sshInfo.host}`,
+    "crayon", "mcp", "sandbox",
+  ];
+
+  // Register via claude mcp add (removes old one first if exists)
+  try {
+    execSync(`claude mcp remove ${MCP_SERVER_NAME} 2>/dev/null`, {
+      stdio: "ignore",
+    });
+  } catch {
+    // May not exist yet — ignore
+  }
+
+  try {
+    execFileSync("claude", [
+      "mcp", "add",
+      "--transport", "stdio",
+      MCP_SERVER_NAME,
+      "--",
+      "ssh",
+      ...sshArgs,
+    ], { stdio: "ignore" });
+    return true;
+  } catch (err) {
+    p.log.error(
+      `Failed to register MCP server: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}
+
+function launchClaude(): void {
+  const result = spawnSync("claude", [], { stdio: "inherit" });
+  process.exit(result.status ?? 0);
+}
+
+export async function handleMcp(appNameArg?: string): Promise<void> {
+  await ensureAuth();
+  const appName = appNameArg ?? (await selectMachine({ excludeStopped: true }));
+
+  const s = p.spinner();
+  s.start("Registering sandbox MCP server...");
+
+  const ok = await registerSandboxMcp(appName);
+  if (!ok) {
+    s.stop(pc.red("Failed to register MCP server"));
+    process.exit(1);
+  }
+
+  s.stop(pc.green(`MCP server "${MCP_SERVER_NAME}" registered for ${appName}`));
+  p.log.info("Launching Claude Code with sandbox access...");
+  p.outro("");
+  launchClaude();
+}
+
 export async function handleSSH(): Promise<void> {
   await ensureAuth();
   const appName = await selectMachine({ excludeStopped: true });

packages/core/src/cli/index.ts

@@ -192,6 +192,14 @@ cloud
     await handleSSH();
   });
 
+cloud
+  .command("mcp [app-name]")
+  .description("Connect local Claude Code to a cloud sandbox via MCP")
+  .action(async (appName?: string) => {
+    const { handleMcp } = await import("./cloud-dev.js");
+    await handleMcp(appName);
+  });
+
 // ============ Workflow commands ============
 const workflow = program.command("workflow").description("Workflow commands");
 
@@ -642,6 +650,14 @@ mcp
     await startMcpServer();
   });
 
+mcp
+  .command("sandbox")
+  .description("Start the sandbox MCP server (filesystem + bash tools for remote access)")
+  .action(async () => {
+    const { startSandboxMcpServer } = await import("./mcp/sandbox-server.js");
+    await startSandboxMcpServer();
+  });
+
 // ============ Install/Uninstall commands ============
 program
   .command("install")

packages/core/src/cli/mcp/sandbox-server.ts

@@ -0,0 +1,46 @@
+import { stdioServerFactory } from "@tigerdata/mcp-boilerplate";
+import { version } from "./config.js";
+import type { ServerContext } from "./types.js";
+import { getSandboxApiFactories } from "./sandbox-tools/index.js";
+
+const serverInfo = {
+  name: "crayon-sandbox-tools",
+  version,
+} as const;
+
+const context: ServerContext = {};
+
+function buildInstructions(): string {
+  const lines = [
+    "You are connected to a remote cloud sandbox via MCP.",
+    "All file and bash operations run via this MCP run on the sandbox.",
+    "The project root is /data/app.",
+  ];
+
+  const flyAppName = process.env.FLY_APP_NAME;
+  if (flyAppName) {
+    const publicUrl = `https://${flyAppName}.fly.dev`;
+    lines.push(
+      `The sandbox's public URL is: ${publicUrl}`,
+      `The dev UI is at: ${publicUrl}/dev/`,
+      "When the app's dev server is running, it is accessible at this public URL you can tell the user to look at it.",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Start the sandbox MCP server in stdio mode.
+ * Exposes filesystem and bash tools for remote sandbox access.
+ */
+export async function startSandboxMcpServer(): Promise<void> {
+  const apiFactories = await getSandboxApiFactories();
+
+  await stdioServerFactory({
+    ...serverInfo,
+    context,
+    apiFactories,
+    instructions: buildInstructions(),
+  });
+}

packages/core/src/cli/mcp/sandbox-tools/bash.ts

@@ -0,0 +1,69 @@
+import type { ApiFactory } from "@tigerdata/mcp-boilerplate";
+import { execFile } from "node:child_process";
+import { z } from "zod";
+import type { ServerContext } from "../types.js";
+
+const DEFAULT_TIMEOUT = 120_000;
+const DEFAULT_CWD = "/data/app";
+
+const inputSchema = {
+  command: z.string().describe("Shell command to execute"),
+  timeout: z
+    .number()
+    .optional()
+    .default(DEFAULT_TIMEOUT)
+    .describe("Timeout in milliseconds (default: 120000)"),
+  cwd: z
+    .string()
+    .optional()
+    .default(DEFAULT_CWD)
+    .describe("Working directory (default: /data/app)"),
+} as const;
+
+const outputSchema = {
+  stdout: z.string().describe("Standard output"),
+  stderr: z.string().describe("Standard error"),
+  exit_code: z.number().describe("Exit code (0 = success)"),
+} as const;
+
+type OutputSchema = {
+  stdout: string;
+  stderr: string;
+  exit_code: number;
+};
+
+export const bashFactory: ApiFactory<
+  ServerContext,
+  typeof inputSchema,
+  typeof outputSchema
+> = () => {
+  return {
+    name: "bash",
+    config: {
+      title: "Bash",
+      description:
+        "Execute a shell command on the sandbox. Returns stdout, stderr, and exit code.",
+      inputSchema,
+      outputSchema,
+    },
+    fn: async ({ command, timeout, cwd }): Promise<OutputSchema> => {
+      return new Promise((resolve) => {
+        execFile(
+          "bash",
+          ["-c", command],
+          {
+            timeout,
+            cwd,
+            maxBuffer: 10 * 1024 * 1024,
+            env: process.env,
+          },
+          (error, stdout, stderr) => {
+            const exit_code =
+              error && "code" in error ? (error.code as number) ?? 1 : error ? 1 : 0;
+            resolve({ stdout, stderr, exit_code });
+          },
+        );
+      });
+    },
+  };
+};

packages/core/src/cli/mcp/sandbox-tools/editFile.ts

@@ -0,0 +1,67 @@
+import type { ApiFactory } from "@tigerdata/mcp-boilerplate";
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import type { ServerContext } from "../types.js";
+
+const inputSchema = {
+  path: z.string().describe("Absolute path to the file to edit"),
+  old_string: z.string().describe("The exact text to find and replace"),
+  new_string: z.string().describe("The replacement text"),
+  replace_all: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Replace all occurrences (default: false, requires unique match)"),
+} as const;
+
+const outputSchema = {
+  success: z.boolean().describe("Whether the edit was applied"),
+  message: z.string().describe("Status message"),
+} as const;
+
+type OutputSchema = {
+  success: boolean;
+  message: string;
+};
+
+export const editFileFactory: ApiFactory<
+  ServerContext,
+  typeof inputSchema,
+  typeof outputSchema
+> = () => {
+  return {
+    name: "edit_file",
+    config: {
+      title: "Edit File",
+      description:
+        "Perform exact string replacement in a file. By default, old_string must appear exactly once (for safety). Set replace_all to replace every occurrence.",
+      inputSchema,
+      outputSchema,
+    },
+    fn: async ({ path, old_string, new_string, replace_all }): Promise<OutputSchema> => {
+      const content = await readFile(path, "utf-8");
+
+      if (!content.includes(old_string)) {
+        return { success: false, message: `old_string not found in ${path}` };
+      }
+
+      if (!replace_all) {
+        const first = content.indexOf(old_string);
+        const second = content.indexOf(old_string, first + 1);
+        if (second !== -1) {
+          return {
+            success: false,
+            message: `old_string appears multiple times in ${path}. Use replace_all or provide more context to make it unique.`,
+          };
+        }
+      }
+
+      const updated = replace_all
+        ? content.replaceAll(old_string, new_string)
+        : content.replace(old_string, new_string);
+
+      await writeFile(path, updated, "utf-8");
+      return { success: true, message: `Applied edit to ${path}` };
+    },
+  };
+};

packages/core/src/cli/mcp/sandbox-tools/index.ts

@@ -0,0 +1,15 @@
+import { readFileFactory } from "./readFile.js";
+import { writeFileFactory } from "./writeFile.js";
+import { editFileFactory } from "./editFile.js";
+import { listDirectoryFactory } from "./listDirectory.js";
+import { bashFactory } from "./bash.js";
+
+export async function getSandboxApiFactories() {
+  return [
+    readFileFactory,
+    writeFileFactory,
+    editFileFactory,
+    listDirectoryFactory,
+    bashFactory,
+  ] as const;
+}