mountable.io

MCP

Run mountable mcp as an MCP server for Claude Code, Claude Desktop or Cursor; its tools; mounting stays a local command.

Use an approved installed mountable mcp, or the npm examples below with lifecycle scripts disabled. Report setup blockers; do not use sudo or a remote shell installer. Follow the agent trust boundary.

mountable mcp serves mountable.io's management operations as MCP tools over stdio. It authenticates like the CLI: with MOUNTABLE_API_KEY, or with the login from mountable login.

Setup

Give the server MOUNTABLE_API_KEY through its environment: inherited from the environment the MCP client starts in, or set under env in the client's configuration. Never pass the key as a command-line argument, where it would end up in process listings and shell history.

Claude Code: .mcp.json in the project. ${MOUNTABLE_API_KEY} is taken from the environment Claude Code runs in, so the key stays out of the file.

{
  "mcpServers": {
    "mountable": {
      "command": "npx",
      "args": ["-y", "--ignore-scripts", "mountable-cli", "mcp"],
      "env": { "MOUNTABLE_API_KEY": "${MOUNTABLE_API_KEY}" }
    }
  }
}

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json). Keep these files private, since they hold the key.

{
  "mcpServers": {
    "mountable": {
      "command": "npx",
      "args": ["-y", "--ignore-scripts", "mountable-cli", "mcp"],
      "env": { "MOUNTABLE_API_KEY": "mtbl_…" }
    }
  }
}

Editor setup guides

Follow the setup for Cursor, Windsurf / Cascade, Cline, Continue or OpenCode. Each page shows the client’s configuration location and how to check its connection.

Tools

After your client connects, use its tool-discovery interface and call list_filesystems. It returns a JSON array of accessible filesystem records; [] is a valid result when none are accessible. An API key sees only its grants; a login with several organisations must pass org_id or configure MOUNTABLE_ORG. For a permissions or sign-in error, follow the returned code and hint rather than retrying a write blindly.

ToolDoes
list_organizationsthe caller's organisations (a key has exactly one)
list_filesystemsthe organisation's filesystems (an API key sees those it has a grant on; a management key sees all)
create_filesystemcreate a filesystem and return it (a management key or an owner's or admin's login)
filesystem_usagestored bytes and files against quotas, and 30-day traffic
create_mount_ticketa one-time mount ticket and a mount_command convenience hint for a person
list_mount_sessionsa filesystem's live mount sessions (an API key sees those it created)
revoke_mount_sessionrevoke a session; its mount stops working
list_webhooksa filesystem's webhooks: URL, state and the last delivery's outcome
delete_webhookdelete a webhook; deliveries to its URL stop
enable_webhookre-enable a webhook disabled after a day of failed deliveries
list_api_keys / revoke_api_keythe organisation's API keys, never their secrets; revoke one
list_s3_keys / revoke_s3_keya filesystem's S3 keys, never their secrets; revoke one
list_grants / set_grant / delete_grantwho may use a filesystem; give or change access; remove it

The key and grant tools take a management key (mtblm_… in MOUNTABLE_API_KEY) or an owner's or admin's login; tickets, sessions and webhooks take an API key. They need CLI 0.10.0 or later.

Tools that work inside an organisation take an optional org_id. Results are the API's JSON; errors return {"error": {"code", "message", "hint"}} with the codes listed on Agents. The tool descriptions carry the retry rules: create_filesystem is not idempotent, and create_mount_ticket takes an idempotency_key to reuse after an unknown outcome. create_mount_ticket also takes an optional max_duration_seconds for the session's lifetime: 12 hours by default, at most 365 days and no longer than the API key.

Creating a webhook and rotating its secret are not tools. Both return a signing secret that stays valid until rotated, and a tool result would put it in the model's context and your provider's transcript. Run mountable webhooks create or rotate-secret, or use the SDKs, where your backend stores the secret. The webhook tools need read-write access to the filesystem.

Creating an API or S3 key is not a tool either, for the same reason: run mountable api-keys create or s3-keys create, or use the SDKs. Deleting a filesystem is mountable fs delete or the SDKs' delete_filesystem.

Mounting stays a local command

Mounting is a long-running process in the sandbox, not a tool call. create_mount_ticket returns the session with its ticket and a mount_command convenience hint for a person. Agents validate the ticket and filesystem ID, then construct the documented command with an approved mount path and the ticket in MOUNTABLE_TICKET, rather than evaluate that hint:

mkdir -p /mnt/mountable && printf '%s\n' "$MOUNTABLE_TICKET" | mountable mount --ticket-stdin --json /mnt/mountable

The command reads the ticket on stdin, so the ticket never appears in an argument list. Any writable directory works in place of /mnt/mountable. Wait for {"event":"mounted"} before using it.