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, share vaults with other users or agents, 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.

5. Set your Sui private key (optional — required for shared vaults)

   Add TUSKYDP_SUI_PRIVATE_KEY to the config’s env block to enable SEAL encryption/decryption on shared vaults.

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",
        "TUSKYDP_SUI_PRIVATE_KEY": "your-sui-ed25519-private-key"
      }
    }
  }
}

Variable	Required	Purpose
TUSKYDP_API_KEY	Yes	API key for authentication
TUSKYDP_PASSWORD	No	Passphrase for private vault encryption/decryption
TUSKYDP_SUI_PRIVATE_KEY	No	Sui Ed25519 private key for SEAL encryption on shared vaults

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
                ←→ Sui Blockchain (SEAL allowlists)

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

The MCP server handles encryption transparently for both private and shared vaults.

Private vaults (passphrase-based)

When uploading to private vaults, 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 private vault 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

Shared vaults (SEAL-based)

When uploading to shared vaults, files are encrypted using the SEAL protocol — Identity-Based Encryption tied to the vault’s on-chain Whitelist. Any member on the Whitelist can decrypt.

To enable shared vault encryption, set TUSKYDP_SUI_PRIVATE_KEY in the config. The server loads the Ed25519 keypair and uses it to sign SEAL decryption requests.

If neither encryption method is configured, the server still works — but operations on encrypted vaults will return a clear error message to the agent.

Available tools

The MCP server exposes 29 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, private, or shared)
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/shared 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/shared 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)
tusky_file_retry	Retry Walrus sync for a failed file, or retry all failed files

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_update	Rename 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_delete	Permanently delete a single item from trash (irreversible)
tusky_trash_empty	Permanently delete all trash (irreversible)

Shared vaults

Tool	Description
tusky_vault_grant_access	Grant a user or agent access to a shared vault by Sui address
tusky_vault_revoke_access	Revoke a member’s access from a shared vault
tusky_vault_list_members	List all members of a shared vault
tusky_vault_list_shared	List shared vaults you’ve been granted access to (not owned)
tusky_account_link_sui	Link a Sui wallet address to your account (required for shared vaults)
tusky_account_unlink_sui	Unlink the Sui wallet address from your account

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.

“SEAL encryption not available” — The agent tried to access a shared vault but the Sui keypair isn’t loaded. Set TUSKYDP_SUI_PRIVATE_KEY in the MCP config’s env block.

“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.

“Shared vaults not enabled” — Your plan doesn’t support shared vaults. Upgrade to Developer, Scale, or Enterprise.

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.