Skip to content
opentusk

MCP Agent Quickstart

The OpenTusk CLI exposes its full surface (vaults, files, folders, search) over the Model Context Protocol so AI agents — Claude Code, Claude Desktop, Cursor, custom MCP clients — can read and write OpenTusk storage directly.

This page is written for the agents themselves (and the humans deploying them). It documents the tools that exist, what to call first, and how to avoid round-trips.

Install

Section titled “Install”

  1. Install the CLI globally

    Terminal window
    npm install -g @opentusk/cli

  2. Log in and capture an API key

    Terminal window
    opentusk login                                  # interactive
    opentusk account api-keys create "agent"        # otk_…

    Or onboard via invite code — one command, no manual key copying:

    Terminal window
    opentusk login --invite-code otinv_...

  3. (Recommended) Set up a Sui key for shared vaults

    Shared (SEAL-encrypted) vaults need a Sui keypair to decrypt content and metadata. Without it, agents can list shared vaults but can’t read filenames or content.

    Terminal window
    opentusk account setup-sui suiprivkey1...

  4. Write the MCP config

    Terminal window
    opentusk mcp install-config              # writes .mcp.json / Claude Desktop config

    That embeds the API key and Sui key (if set) so the host agent can launch opentusk mcp serve.

The first call an agent should make

Section titled “The first call an agent should make”
opentusk_account_info()

Returns identity, plan, storage usage, linked Sui address, vault count, the default vault ID, and (when the local index is running) the latest file activity timestamp. That’s enough context to decide what to do next without follow-up calls.

Pre-loading tool schemas

Section titled “Pre-loading tool schemas”

Many MCP clients (notably Claude Code) defer tool schemas — they list tool names but you have to look up parameter schemas via tool_search before calling. For an OpenTusk-heavy session, pre-load the schemas you’ll actually need in one go:

tool_search select:opentusk_account_info,opentusk_vault_list,opentusk_vault_tree,opentusk_file_list,opentusk_file_read,opentusk_file_get_chunks,opentusk_search,opentusk_folder_get_contents

That’s eight tools that cover ~95% of agent workflows. Other tools (opentusk_vault_create, opentusk_file_upload, etc.) can be loaded on demand.

Tool index

Section titled “Tool index”

Discovery — what’s here?

Section titled “Discovery — what’s here?”
ToolWhen to use
opentusk_account_infoFirst call in a new session. Identity + storage + default vault.
opentusk_vault_listList vaults. Lean by default (no SEAL crypto fields). Pass verbose=true only if you need on-chain object IDs.
opentusk_vault_treePrefer this for “what’s in this vault.” Returns folders + files with paths + decrypted filenames in one call. Uses the local index when available, falls back to walking the API.
opentusk_folder_get_contentsFiles + subfolders at one folder level. Use only when you don’t want the full tree.

Reading

Section titled “Reading”
ToolWhen to use
opentusk_file_listPaginated file list, scoped by vault or folder. Returns decrypted filenames and folderPath for shared-vault files (no need to fall back to search).
opentusk_file_readRead a file inline (text or base64). Handles SEAL decryption + cold-file rehydration. Right tool when you want to inspect/summarize content.
opentusk_file_read_batchRead up to 50 files in one call with bounded concurrency. Per-file failures don’t fail the batch. Use this when you need to summarize / diff / process a known set of files.
opentusk_file_downloadSame as read but saves to disk. Use when your environment has a writable filesystem.
opentusk_searchSemantic + filename-pattern search. Pass an empty query together with namePattern: "2026-05-*.md" for pure filename matching.
opentusk_file_get_chunksWiden context around a search hit (e.g. fetch chunks [n-1, n+2] for surrounding paragraphs). Fastest path to reconstruct a fully-text-indexed file too.

Writing

Section titled “Writing”
ToolWhen to use
opentusk_vault_createNew vault. Default visibility is shared (SEAL-encrypted).
opentusk_file_uploadUpload from a local disk path.
opentusk_file_createUpload from raw content (text or base64). Use this in sandboxed environments without a writable filesystem.
opentusk_folder_create / opentusk_folder_update / opentusk_folder_deleteFolder CRUD.

Less common but useful

Section titled “Less common but useful”

opentusk_file_get, opentusk_file_delete, opentusk_file_retry, opentusk_trash_list, opentusk_trash_restore, opentusk_trash_delete, opentusk_trash_empty, opentusk_vault_grant_access, opentusk_vault_revoke_access, opentusk_vault_list_members, opentusk_vault_list_shared, opentusk_account_link_sui, opentusk_account_unlink_sui, opentusk_index_sync.

Common patterns

Section titled “Common patterns”

”Show me what’s in vault X”

Section titled “”Show me what’s in vault X””
opentusk_vault_tree(vaultId: "...")

One call. Returns { folders: [{path, name, fileCount}], files: [{id, name, path, mimeType, sizeBytes, modifiedAt}] }. Don’t reach for folder_list + file_list + search to assemble this yourself.

”Find all files matching 2026-05-*.md in this vault”

Section titled “”Find all files matching 2026-05-*.md in this vault””
opentusk_search(query: "", vaultId: "...", namePattern: "2026-05-*.md")

An empty query with a name filter runs as a metadata-only search — no embedding, no semantic ranking, just SQL LIKE.

”Summarize this file”

Section titled “”Summarize this file””
opentusk_file_read(fileId: "...")     # full content if it fits in your context
# or
opentusk_search(query: "summary topic", vaultId: "...")
opentusk_file_get_chunks(fileId: "<from-search>", startChunk: 0, endChunk: 50)

For fully-text-indexed files, file_get_chunks reads from the local index (no SEAL hop, no network) — significantly faster than file_read.

”Summarize all of last month’s journal entries”

Section titled “”Summarize all of last month’s journal entries””
opentusk_search(query: "", vaultId: "...", namePattern: "2026-04-*-journal.md")
opentusk_file_read_batch(fileIds: ["<id-1>", "<id-2>", ...], concurrency: 5)

The batch call returns each file’s content (text or base64) plus its real name. Per-file errors don’t fail the batch — failed entries carry an error field instead of content.

”What did I edit recently?”

Section titled “”What did I edit recently?””
opentusk_account_info()                    # lastActivityAt across the whole account
opentusk_vault_list()                       # lastFileActivityAt per vault

Encryption model in one paragraph

Section titled “Encryption model in one paragraph”

Public vaults: plaintext on storage, plaintext over the wire to you. Shared vaults: SEAL-encrypted; the CLI process holds the Sui keypair and decrypts both content and filenames locally. The OpenTusk API never sees plaintext for shared vaults. Filenames in file_list are decrypted client-side before being returned to the agent.

If OPENTUSK_SUI_PRIVATE_KEY isn’t set, shared-vault filenames appear as storage UUIDs and content reads will fail — set the key, or restrict the agent to public vaults.

Section titled “Related”