MCP Tools

The OpenTusk MCP server exposes 34 tools that AI agents can call directly via the Model Context Protocol.

Category	Count	Tools
Account	3	account_info, account_link_sui, account_unlink_sui
Vaults	6	vault_create, vault_list, vault_get, vault_update, vault_delete, vault_tree
Shared vaults	4	vault_grant_access, vault_revoke_access, vault_list_members, vault_list_shared
Files	10	file_upload, file_create, file_read, file_read_batch, file_download, file_list, file_get, file_get_chunks, file_delete, file_retry
Folders	5	folder_create, folder_list, folder_get_contents, folder_update, folder_delete
Trash	4	trash_list, trash_restore, trash_delete, trash_empty
Search	2	search, index_sync (only when @opentusk/indexer is reachable)

Architecture

Agent (Claude Code / Desktop / Cursor)
  ↕ stdin/stdout (JSON-RPC)
MCP Server (opentusk mcp serve)
  ↕ @opentusk/sdk
OpenTusk API (api.opentusk.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 JSON-RPC. All human-readable output goes to stderr — stdout is reserved for the MCP protocol.

Setup

npm install -g @opentusk/cli
opentusk login --api-key otk_your_key
opentusk mcp install-config --target claude-code  # or claude-desktop, cursor

See the quickstart for your agent: Claude Code, Claude Desktop, Cursor.

Manual configuration

{
  "mcpServers": {
    "opentusk": {
      "command": "opentusk",
      "args": ["mcp", "serve"],
      "env": {
        "OPENTUSK_API_KEY": "otk_your_key",
        "OPENTUSK_SUI_PRIVATE_KEY": "suiprivkey1..."
      }
    }
  }
}

Variable	Required	Purpose
OPENTUSK_API_KEY	Yes	API key for authentication
OPENTUSK_SUI_PRIVATE_KEY	No	Sui Ed25519 private key for SEAL encryption on shared vaults

Config locations

Agent	Target	Config file
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

Encryption

The MCP server handles SEAL encryption transparently for shared vaults. When uploading, files are encrypted using SEAL IBE tied to the vault’s on-chain Whitelist. When downloading, the server signs a SessionKey with the Sui keypair to prove membership.

If OPENTUSK_SUI_PRIVATE_KEY is not set, shared vault operations return a clear error. Public vaults work without it.

Tool reference

Account

opentusk_account_info

Get account info — email, plan, storage usage, encryption status.

Parameters: None

---

opentusk_account_link_sui

Link a Sui wallet address to the account. Required for shared vault access.

Parameter	Type	Required	Description
suiAddress	string	Yes	Sui wallet address (0x + 64 hex chars)

---

opentusk_account_unlink_sui

Unlink the Sui wallet address from the account.

Parameters: None

---

Vaults

opentusk_vault_create

Create a vault.

Parameter	Type	Required	Default	Description
name	string	Yes	—	Vault name
description	string	No	—	Vault description
visibility	string	No	"shared"	"public" or "shared"

Note

Vault visibility is immutable after creation.

---

opentusk_vault_list

List the account’s vaults. Returns a lean summary by default: id, name, visibility, fileCount, totalSizeBytes, and (when the local indexer is running) lastFileActivityAt.

Parameter	Type	Required	Default	Description
verbose	boolean	No	false	Include SEAL on-chain crypto metadata (sealAllowlistObjectId, sealCapObjectId, sealPackageId, sealKeyServerIds, sealThreshold). Only useful for wallet-side SEAL operations.

---

opentusk_vault_get

Get vault details by ID.

Parameter	Type	Required	Description
vaultId	string	Yes	Vault ID

---

opentusk_vault_update

Update vault name or description.

Parameter	Type	Required	Description
vaultId	string	Yes	Vault ID
name	string	No	New vault name
description	string	No	New description

---

opentusk_vault_delete

Delete a vault.

Parameter	Type	Required	Default	Description
vaultId	string	Yes	—	Vault ID
force	boolean	No	false	Delete even if vault has files (moves files to trash first)

---

opentusk_vault_tree

Enumerate every folder and file in a vault as a flat tree with paths and decrypted filenames. Prefer this over folder_list + file_list when browsing a vault — one call instead of N. Uses the local search index when available (fastest path); falls back to walking the API and decrypting SEAL filenames client-side.

Parameter	Type	Required	Default	Description
vaultId	string	Yes	—	Vault ID to enumerate
includeFiles	boolean	No	true	Set false for a folder-only listing
maxDepth	number	No	10	Max folder depth to descend (0–20). Only honored on the SDK fallback path.

Returns { folders: [{ id, path, name, fileCount }], files: [{ id, name, path, mimeType, sizeBytes, modifiedAt }] }.

---

Files

opentusk_file_upload

Upload a file from a local disk path. Encrypts automatically for shared vaults.

Parameter	Type	Required	Description
filePath	string	Yes	Local file path
vaultId	string	Yes	Target vault ID
folderId	string	No	Target folder ID

Best for agents with filesystem access (Claude Code, Cursor).

---

opentusk_file_create

Create a file from raw text or base64 content. Encrypts automatically for shared vaults.

Parameter	Type	Required	Default	Description
name	string	Yes	—	File name
content	string	Yes	—	File content (text or base64)
encoding	string	No	"utf-8"	"utf-8" or "base64"
vaultId	string	Yes	—	Target vault ID
folderId	string	No	—	Target folder ID

Best for sandboxed agents without filesystem access (Claude Desktop).

---

opentusk_file_download

Download a file to a local disk path. Decrypts automatically for shared vaults.

Parameter	Type	Required	Description
fileId	string	Yes	File ID
outputPath	string	Yes	Local output path

---

opentusk_file_read

Read file content inline. Returns text for text files, base64 for binary. Handles SEAL decryption + cold-file rehydration transparently.

Parameter	Type	Required	Description
fileId	string	Yes	File ID

Best for inspecting a single file’s content. For multiple files in one call, use opentusk_file_read_batch.

---

opentusk_file_read_batch

Read up to 50 files in one call with bounded concurrency. Per-file failures don’t fail the batch — failed entries carry an error field instead of content. Use this when you need to summarize, diff, or process a known set of files.

Parameter	Type	Required	Default	Description
fileIds	string[]	Yes	—	File IDs to read (1–50)
concurrency	number	No	5	Max simultaneous file fetches (1–10)

---

opentusk_file_get_chunks

Return a contiguous range of chunks from an indexed file. Faster than file_read for fully-text-indexed files because chunks come straight from the local index — no SEAL hop, no network. Use it to widen context around a search hit (e.g. fetch chunks [n-1, n+2] for surrounding paragraphs).

Parameter	Type	Required	Default	Description
fileId	string	Yes	—	File ID
startChunk	number	No	0	First chunk index (inclusive)
endChunk	number	No	very large	Last chunk index (inclusive)

Only useful when the file has been indexed by @opentusk/indexer.

---

opentusk_file_list

List files, optionally filtered by vault or folder.

Parameter	Type	Required	Description
vaultId	string	No	Filter by vault
folderId	string	No	Filter by folder
limit	number	No	Max results
cursor	string	No	Pagination cursor

---

opentusk_file_get

Get file metadata by ID.

Parameter	Type	Required	Description
fileId	string	Yes	File ID

---

opentusk_file_delete

Soft-delete a file (moves to trash, restorable for 7 days).

Parameter	Type	Required	Description
fileId	string	Yes	File ID

---

opentusk_file_retry

Retry Walrus sync for a failed file, or retry all failed files.

Parameter	Type	Required	Description
fileId	string	No	File ID (omit to retry all failed files)

---

Folders

opentusk_folder_create

Create a folder in a vault.

Parameter	Type	Required	Description
vaultId	string	Yes	Vault ID
name	string	Yes	Folder name
parentId	string	No	Parent folder ID (for nesting)

---

opentusk_folder_list

List folders in a vault.

Parameter	Type	Required	Description
vaultId	string	Yes	Vault ID
parentId	string	No	List children of a specific parent

---

opentusk_folder_get_contents

Get files and subfolders in a folder.

Parameter	Type	Required	Description
folderId	string	Yes	Folder ID

---

opentusk_folder_update

Rename a folder.

Parameter	Type	Required	Description
folderId	string	Yes	Folder ID
name	string	Yes	New folder name

---

opentusk_folder_delete

Delete a folder.

Parameter	Type	Required	Description
folderId	string	Yes	Folder ID

---

Trash

opentusk_trash_list

List all trashed items.

Parameters: None

---

opentusk_trash_restore

Restore a file or vault from trash.

Parameter	Type	Required	Description
id	string	Yes	Trashed item ID

---

opentusk_trash_delete

Permanently delete a single item from trash. Irreversible.

Parameter	Type	Required	Description
id	string	Yes	Trashed item ID

---

opentusk_trash_empty

Permanently delete all trash. Irreversible.

Parameters: None

---

Shared vaults

opentusk_vault_grant_access

Grant a user or agent access to a shared vault by Sui address.

Parameter	Type	Required	Description
vaultId	string	Yes	Vault ID
suiAddress	string	Yes	Member’s Sui address

---

opentusk_vault_revoke_access

Revoke a member’s access from a shared vault.

Parameter	Type	Required	Description
vaultId	string	Yes	Vault ID
memberId	string	Yes	Member ID (from opentusk_vault_list_members)

---

opentusk_vault_list_members

List all members of a shared vault.

Parameter	Type	Required	Description
vaultId	string	Yes	Vault ID

---

opentusk_vault_list_shared

List shared vaults the user is a member of (not owner).

Parameters: None

---

Search

Search tools are only registered when @opentusk/indexer is installed and reachable (either spawned over stdio or via OPENTUSK_INDEXER_URL). If the indexer isn’t available, these tools are silently omitted — no error. See the Semantic Search guide for setup.

opentusk_search

Run a semantic query across indexed files. Combines vector-space semantic ranking with filename-pattern matching — pass an empty query with namePattern for pure SQL LIKE filename search (no embedding, fastest path).

Parameter	Type	Required	Default	Description
query	string	Yes	—	Natural-language query. Pass an empty string for pure filename-pattern search.
vaultId	string	No	—	Filter by vault
folderPath	string	No	—	Folder path prefix (recursive)
mimeType	string	No	—	MIME type filter (e.g. "text/markdown")
namePattern	string	No	—	Shell-style glob matched against filename, case-insensitive. e.g. "2026-05-*.md", "*.pdf".
nameRegex	string	No	—	Regex matched against filename, case-insensitive. Combined with namePattern (both must match).
limit	number	No	10	Max results (1–50)
minScore	number	No	0.3	Similarity threshold 0–1. Ignored when query is empty.

Returns a ranked array with filename, vault, folder, score, and matching chunks.

---

opentusk_index_sync

Sync vault files into the local index so search results are up to date. Incremental by default — only walks files whose content hash has changed.

Parameter	Type	Required	Default	Description
vaultId	string	No	—	Sync a specific vault only (omit to sync all)
full	boolean	No	false	Re-walk every file even if already indexed
includeBinary	boolean	No	false	Download bodies even for files classified as non-indexable
sniffLimitBytes	number	No	1048576	Size cap (bytes) for octet-stream / unknown-MIME files. Above this they become metadata-only.

Troubleshooting

Symptom	Fix
”SEAL encryption not available”	Set OPENTUSK_SUI_PRIVATE_KEY in the MCP config’s env block
”Invalid API key”	Create a new key at app.opentusk.ai or via opentusk account api-keys create
”Command not found”	Re-run opentusk mcp install-config to regenerate with absolute paths
File stuck in “rehydrating”	Cold files need to be fetched from Walrus — polls automatically for up to 60 seconds
Agent can’t write files	Sandboxed agents: use opentusk_file_create / opentusk_file_read instead of upload/download
”Shared vaults not enabled”	Link your Sui address: opentusk account link-sui <address>

SKILL.md Install the SKILL.md to teach Claude Code how to use these tools.

CLI reference Full CLI command reference.