Undisk MCP works with every major AI coding client. One terminal command registers a versioned, reversible file workspace — and every write your agent makes from that point forward is automatically snapshotted and restorable.

This guide covers the three clients developers ask about most: Claude Desktop, OpenAI Codex, and Gemini CLI. If your client supports remote HTTP, you can skip the proxy entirely. Instructions for that are at the end.

Prerequisites

You need two things before running any of the setup commands below:

  1. An Undisk API key — sign up at mcp.undisk.app and generate a key from the dashboard. It starts with sk_live_.
  2. Node.js 18+ — the stdio proxy runs on Node. If you have npx available, you are good to go.

Claude Desktop

The fastest path. A single npx command configures everything:

npx @undisk-mcp/setup-claude

The setup script finds your claude_desktop_config.json, adds the Undisk server entry, and prompts for your API key. Restart Claude Desktop after running it, and the Undisk tools appear in the tool picker.

Under the hood, the script registers @undisk-mcp/stdio-proxy as a stdio-based MCP server with your key baked into the environment block.

OpenAI Codex

Codex has a built-in mcp add command. Pass the API key with --env so the proxy can authenticate:

codex mcp add undisk --env UNDISK_API_KEY=sk_live_YOUR_KEY -- npx -y @undisk-mcp/stdio-proxy

Replace sk_live_YOUR_KEY with your actual key. Codex stores the configuration locally and starts the proxy when you begin a session. You can verify it is registered by opening Settings → MCP Servers inside Codex.

To test, ask Codex to “list files in my Undisk workspace.” If it calls list_files, you are connected.

Gemini CLI

Gemini CLI connects directly over HTTP — no proxy needed:

gemini mcp add --transport http --scope user -H 'Authorization: Bearer sk_live_YOUR_KEY' undisk https://mcp.undisk.app/v1/mcp

You can confirm the server is registered with:

gemini mcp list

Start a Gemini session and ask it to create a file. If Undisk tools show up in the tool list, the connection is live.

How the Stdio Proxy Works

Claude Desktop, Codex, and other clients that only support stdio expect MCP servers to communicate over stdin and stdout — the stdio transport. Undisk’s server runs on Cloudflare’s edge and speaks Streamable HTTP. Something needs to bridge the two.

Note: Gemini CLI supports HTTP transport natively, so it connects directly to Undisk without a proxy.

That bridge is @undisk-mcp/stdio-proxy. Here is what happens when your client sends a message:

  1. The client writes a JSON-RPC message to stdin.
  2. The proxy reads the line, parses it, and determines whether it is a request (has an id) or a notification (no id).
  3. Requests are forwarded to https://mcp.undisk.app/mcp over HTTP with your API key in the headers. The server’s JSON-RPC response is written back to stdout.
  4. Notifications (like notifications/initialized) are forwarded but produce no response — the proxy stays silent, which is what the MCP spec requires.
  5. Messages are processed serially through a promise queue to prevent race conditions on stdout.

The proxy is stateless. All workspace state lives on Undisk’s edge servers. If the proxy crashes, restart it — nothing is lost.

Direct HTTP — No Proxy Needed

If your MCP client supports remote Streamable HTTP transport natively, you do not need the stdio proxy at all. Connect directly:

SettingValue
URLhttps://mcp.undisk.app/mcp
Auth headerAuthorization: Bearer sk_live_YOUR_KEY
Alt headerx-api-key: sk_live_YOUR_KEY

Clients that support this today include GitHub Copilot, Cursor, Windsurf, and VS Code (via the MCP extension). For example, in VS Code’s .vscode/mcp.json:

{
  "servers": {
    "undisk": {
      "type": "http",
      "url": "https://mcp.undisk.app/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

No proxy process, no npm install, no stdin/stdout — just HTTPS.

Verify Your Connection

Regardless of which client you use, the quickest way to verify the setup is working:

  1. Ask the agent: “What Undisk tools do you have?” — it should list tools like write_file, read_file, list_versions, restore_version, and others.
  2. Create a test file: Ask the agent to write a file called hello.txt with any content.
  3. Check versions: Ask the agent to list versions of hello.txt. You should see at least one version with a timestamp and content hash.
  4. Restore: Ask the agent to write hello.txt again with different content, then restore the first version. The original content should come back.

If all four steps work, you have a fully functional versioned workspace. Every file operation from here on creates an immutable snapshot — no extra configuration needed.

What You Get

Once connected, your agent has access to every Undisk MCP tool:

  • write_file / read_file — standard file operations, but every write creates a version
  • list_versions — see the full history of any file
  • restore_version — roll back a single file to any prior state in under 50 ms
  • diff_versions — see exactly what changed between two versions
  • search_files — full-text search across your workspace
  • list_files — browse the workspace directory tree
  • delete_file — soft-delete with version preservation

Every tool call is logged in a tamper-evident audit trail. You can inspect the history, attribute changes to specific agents, and prove compliance if you need to.

One command. Full undo. Every client.

Frequently Asked Questions

Does Undisk work with MCP clients not listed here?

Yes. Undisk speaks standard MCP over Streamable HTTP. Any client that supports remote MCP servers — Cursor, Windsurf, VS Code, GitHub Copilot — can connect directly to https://mcp.undisk.app/mcp without a proxy. See the Direct HTTP section for the universal setup.

Why do some clients need the stdio proxy?

Claude Desktop, OpenAI Codex, and Gemini CLI expect MCP servers to communicate over stdin and stdout. The stdio proxy bridges that to Undisk's Streamable HTTP endpoint. Clients that already support remote HTTP transport, like Cursor or GitHub Copilot, connect directly without a proxy.

Can I use Undisk with multiple clients at the same time?

Yes. Each client opens its own session against your workspace. Undisk handles concurrent access — every write from every client creates its own immutable version. There are no conflicts because every mutation is append-only.

What happens if the stdio proxy crashes?

The MCP client will report a disconnection and typically offer to restart the server. Because npx fetches the latest published version each time, a restart picks up any bug fixes automatically. No workspace data is lost — all state lives server-side.

Is my API key stored securely?

When using the --env flag with Codex or Gemini CLI, the key is stored in the client's local configuration file and passed as an environment variable to the proxy process. It is never sent to any third party. For Claude Desktop, the setup script writes the key into claude_desktop_config.json with the same model.