MCP Server

Tusky includes a built-in MCP (Model Context Protocol) server that lets AI agents interact with your storage directly. Agents can create vaults, upload and download files, manage folders, and handle encryption — all through standardized tool calls.

Supported agents

Agent	Target name	Config location
Claude Code	claude-code	.mcp.json in project root
Claude Desktop	claude-desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	cursor	~/.cursor/mcp.json

Quick setup

1. Install the CLI

   npm install -g @tuskydp/cli

2. Authenticate

   tusky login --api-key tdp_your_key

3. Install the MCP config

   Claude Code

   tusky mcp install-config --target claude-code

   Claude Desktop

   tusky mcp install-config --target claude-desktop

   Cursor

   tusky mcp install-config --target cursor

4. Set your encryption passphrase (optional — required for private vaults)

   Add TUSKYDP_PASSWORD to the generated config file’s env block, or set it as an environment variable.

The install-config command writes the MCP server configuration to the correct location for your agent. It resolves absolute paths to the tusky binary to avoid PATH issues in sandboxed agent environments.

Manual configuration

If you prefer to configure manually, add this to your agent’s MCP config file:

{
  "mcpServers": {
    "tusky": {
      "command": "tusky",
      "args": ["mcp", "serve"],
      "env": {
        "TUSKYDP_API_KEY": "tdp_your_key",
        "TUSKYDP_PASSWORD": "your-encryption-passphrase"
      }
    }
  }
}

Caution

Use absolute paths for the command field if your agent runs in a sandboxed environment. The install-config command handles this automatically.

Architecture

Agent (Claude Code / Desktop / Cursor)
  ↕ stdin/stdout (JSON-RPC)
MCP Server (tusky mcp serve)
  ↕ @tuskydp/sdk
Tusky API (api.tusky.ai)
  ↕
Hot Cache (S3) ←→ Walrus Network

The MCP server runs as a subprocess of the agent, communicating over stdin/stdout using the JSON-RPC protocol. It uses the TypeScript SDK internally to make API calls. All human-readable output goes to stderr — stdout is reserved for the MCP protocol.

Encryption for private vaults

The MCP server handles encryption transparently for private vaults. When uploading, files are encrypted client-side with AES-256-GCM before leaving the agent’s machine. When downloading or reading, files are decrypted automatically.

To enable encryption, the server needs your passphrase. It resolves the master key in this order:

1. TUSKYDP_PASSWORD environment variable — derives the wrapping key via PBKDF2 (600K iterations), unwraps the master key
2. Session file fallback — reads from ~/.tusky/session.enc if you’ve previously run tusky encryption unlock

If neither is available, the server still works — but operations on private vaults will return a clear error message to the agent explaining that encryption is not unlocked.

Available tools

The MCP server exposes 20 tools that agents can call directly.

Account

Tool	Description
tusky_account_info	Get account info — email, plan, storage usage, encryption status

Vaults

Tool	Description
tusky_vault_create	Create a vault with a name and visibility (public or private)
tusky_vault_list	List all vaults
tusky_vault_get	Get vault details by ID
tusky_vault_update	Update vault name or description
tusky_vault_delete	Delete a vault (use force: true to delete with files)

Files

Tool	Description
tusky_file_upload	Upload a file from a local disk path. Encrypts for private vaults.
tusky_file_create	Create a file from raw text or base64 content — for sandboxed agents without filesystem access
tusky_file_download	Download a file to a local disk path. Decrypts for private vaults.
tusky_file_read	Read file content inline (text or base64) — for sandboxed agents
tusky_file_list	List files, optionally filtered by vault or folder
tusky_file_get	Get file metadata by ID
tusky_file_delete	Soft-delete a file (moves to trash, restorable for 7 days)

Note

tusky_file_upload and tusky_file_download use local filesystem paths — best for agents with disk access like Claude Code. tusky_file_create and tusky_file_read pass content inline — best for sandboxed agents like Claude Desktop.

Folders

Tool	Description
tusky_folder_create	Create a folder in a vault
tusky_folder_list	List folders in a vault
tusky_folder_get_contents	Get files and subfolders in a folder
tusky_folder_delete	Delete a folder

Trash

Tool	Description
tusky_trash_list	List all trashed items
tusky_trash_restore	Restore a file or vault from trash
tusky_trash_empty	Permanently delete all trash (irreversible)

Troubleshooting

“Encryption is not unlocked” — The agent tried to access a private vault but the master key isn’t available. Set TUSKYDP_PASSWORD in the MCP config’s env block, or run tusky encryption unlock to create a session file.

“Invalid API key” — The TUSKYDP_API_KEY in your config is missing or incorrect. Create a new key at app.tusky.ai or via tusky api-keys create.

“Command not found” — The agent can’t find the tusky binary. Re-run tusky mcp install-config to regenerate the config with absolute paths, or set the command field to the full path (e.g., /usr/local/bin/tusky).

File stuck in “rehydrating” — Cold files need to be fetched back from Walrus before download. The MCP server polls automatically for up to 60 seconds. If it times out, try again — the rehydration may still be in progress.

Agent can’t write files — Sandboxed agents (like Claude Desktop) may not have filesystem access. Use tusky_file_create and tusky_file_read instead of tusky_file_upload and tusky_file_download.

Add the Tusky SKILL.md

For Claude Code users, pair the MCP server with the Tusky SKILL.md — it teaches Claude how to use the tools, what rules to follow, and which workflows to apply. One command:

mkdir -p .claude/skills/tusky && curl -sL \
  https://docs.tusky.ai/skills/SKILL.md \
  -o .claude/skills/tusky/SKILL.md

After that, ask Claude to “save this file to Tusky” or “back up the project” and it handles the rest. See the full SKILL.md reference for what’s inside.

Agent skills & SKILL.md Full SKILL.md content, installation options, and workflow recipes.

CLI reference Full command reference for the Tusky CLI.