Quickstart - Undisk MCP

Create an account

Create an API key

Keys are shown once after creation at https://mcp.undisk.app/keys.

Connect your client

Use one of the setups below, then verify that your client can call tools/list.

Verify the connection

Expected tools/list response shape (trimmed):

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      { "name": "read_file" },
      { "name": "write_file" },
      { "name": "list_versions" }
    ]
  }
}

Common failures:

401: invalid/missing key, or wrong header shape.
429: tier/rate cap reached, wait and retry.
Empty/invalid MCP response: usually client transport misconfiguration.

How versioning works

Undisk keeps workspace state as the latest version pointer per path. Writes, deletes, moves, log appends, and restores all append new history instead of mutating old content in place.

Popular setups

Best for Claude Desktop. This writes the Undisk stdio bridge into claude_desktop_config.json and prompts for your key if you omit --api-key.

npx @undisk-mcp/setup-claude --api-key sk_live_YOUR_KEY_HERE

Restart Claude Desktop after the command completes.

claude mcp add --transport http --header "Authorization: Bearer sk_live_YOUR_KEY_HERE" undisk https://mcp.undisk.app/v1/mcp

Create .cursor/mcp.json in your project or ~/.cursor/mcp.json for a global setup:

{
  "mcpServers": {
    "undisk": {
      "url": "https://mcp.undisk.app/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UNDISK_API_KEY}"
      }
    }
  }
}

Export UNDISK_API_KEY before launching Cursor.

Create .vscode/mcp.json in your workspace or open your user mcp.json profile config:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "undisk-api-key",
      "description": "Undisk API key",
      "password": true
    }
  ],
  "servers": {
    "undisk": {
      "type": "http",
      "url": "https://mcp.undisk.app/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:undisk-api-key}"
      }
    }
  }
}

Edit ~/.copilot/mcp-config.json or add the server interactively with /mcp add:

{
  "mcpServers": {
    "undisk": {
      "type": "http",
      "url": "https://mcp.undisk.app/v1/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY_HERE"
      },
      "tools": ["*"]
    }
  }
}

Start with tools: ["*"] while you validate the integration, then narrow the list if you want stricter tool scope.

Add Undisk to your user-level config with Gemini’s native HTTP transport:

gemini mcp add --transport http --scope user --header "Authorization: Bearer sk_live_YOUR_KEY_HERE" undisk https://mcp.undisk.app/v1/mcp

Leave off --trust unless you want to bypass per-tool confirmation prompts.

More clients and transport options

Windsurf

Edit ~/.codeium/mcp_config.json:

{
  "mcpServers": {
    "undisk": {
      "serverUrl": "https://mcp.undisk.app/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UNDISK_API_KEY}"
      }
    }
  }
}

Export UNDISK_API_KEY before launching Windsurf.

GitHub Copilot Cloud Agent

Add .github/copilot/mcp.json to your repository:

{
  "mcpServers": {
    "undisk": {
      "type": "http",
      "url": "https://mcp.undisk.app/v1/mcp",
      "headers": {
        "x-api-key": "$COPILOT_MCP_UNDISK_API_KEY"
      },
      "tools": ["*"]
    }
  }
}

Important: Create a copilot environment secret named COPILOT_MCP_UNDISK_API_KEY before assigning work to the cloud agent.

WebSocket Transport (fastest p50 4ms reads)

wss://mcp.undisk.app/ws?token=sk_live_YOUR_KEY_HERE

Token in the query string is necessary because many WebSocket clients do not support custom headers during the upgrade handshake. Prefer Streamable HTTP when your client supports it.

Direct HTTP

URL:   https://mcp.undisk.app/v1/mcp
Auth:  Authorization: Bearer sk_live_YOUR_KEY_HERE

Google ADK (Python)

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

root_agent = LlmAgent(
    model="gemini-2.0-flash",
    name="undisk_agent",
    instruction="You have a versioned file workspace via Undisk.",
    tools=[McpToolset(connection_params=StreamableHTTPConnectionParams(
        url="https://mcp.undisk.app/v1/mcp",
        headers={"Authorization": "Bearer sk_live_YOUR_KEY_HERE"},
    ))],
)

LlamaIndex (Python)

import asyncio
import os

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

UNDISK_API_KEY = os.environ["UNDISK_API_KEY"]

async def main():
    mcp_client = BasicMCPClient(
        "https://mcp.undisk.app/v1/mcp",
        headers={"Authorization": f"Bearer {UNDISK_API_KEY}"},
    )
    tool_spec = McpToolSpec(client=mcp_client)
    tools = await tool_spec.to_tool_list_async()

    agent = FunctionAgent(
        name="undisk_agent",
        description="Agent with access to Undisk MCP tools.",
        llm=OpenAI(model="gpt-4o-mini"),  # reads OPENAI_API_KEY from env
        tools=tools,
        system_prompt="Use Undisk tools for versioned file operations.",
    )

    response = await agent.run("List files at workspace root.")
    print(str(response))

asyncio.run(main())

Starter use cases

Let an agent draft changes, then restore only the broken file if review fails.
Keep shared memory files (notes/logs) across Claude, Cursor, and CLI runs.
Produce audit evidence with immutable history and diff snapshots.

Next steps

Integration-specific setup: /integrations
SDK implementation patterns: /sdk-reference
First operational workflow: /getting-started/first-workflow-write-diff-restore

​Verify the connection

​How versioning works

​Popular setups

​More clients and transport options

​Windsurf

​GitHub Copilot Cloud Agent

​WebSocket Transport (fastest p50 4ms reads)

​Direct HTTP

​Google ADK (Python)

​LlamaIndex (Python)

​Starter use cases

​Next steps