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.
| Tool | Does |
|---|---|
list_organizations | the caller's organisations (a key has exactly one) |
list_filesystems | the organisation's filesystems (an API key sees those it has a grant on; a management key sees all) |
create_filesystem | create a filesystem and return it (a management key or an owner's or admin's login) |
filesystem_usage | stored bytes and files against quotas, and 30-day traffic |
create_mount_ticket | a one-time mount ticket and a mount_command convenience hint for a person |
list_mount_sessions | a filesystem's live mount sessions (an API key sees those it created) |
revoke_mount_session | revoke a session; its mount stops working |
list_webhooks | a filesystem's webhooks: URL, state and the last delivery's outcome |
delete_webhook | delete a webhook; deliveries to its URL stop |
enable_webhook | re-enable a webhook disabled after a day of failed deliveries |
list_api_keys / revoke_api_key | the organisation's API keys, never their secrets; revoke one |
list_s3_keys / revoke_s3_key | a filesystem's S3 keys, never their secrets; revoke one |
list_grants / set_grant / delete_grant | who 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/mountableThe 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.