BlinkVault MCP

Connect your AI app

Most apps only need the server URL — you'll sign in to BlinkVault and approve access (read-only by default; tick "Make changes" to allow edits). Apps without sign-in support use an MCP token instead. On the Free plan MCP is read-only (search, fetch and read tools); Plus and Pro unlock tools that make changes.

https://dev.blink.vaultica.io/api/mcp

Plans & permissions

• Free: read-only tools (search, fetch, list and get tools). Tools that change your vault are hidden.
• Plus and Pro: every tool, once the connection also has write access.
• Write access is granted per connection: tick Make changes when your AI client asks you to sign in, or create a key below with vault:write. To change an existing connection, disconnect it in Connected apps and connect again.
• Limit a connection to some folders — tick Only these folders when connecting (or when creating a key below). The connection then cannot see, search or change anything outside them, so company documents and personal notes stay apart. Secret and locked folders are never included.
• Ask your AI client to call get_capabilities: it lists your plan, the connection's permissions and exactly which tools it can use.

How it behaves

• Folders. list_zones gives folder ids; create_zone, move_file and upload_file's zone_id file things. An unknown folder id is an error, never a silent fallback.
• Locked folders. The Secret folder and folders that need an unlock step are never searched, read, edited or shared over MCP. Reading one returns a zone_locked error, not an empty result. Over MCP a folder's protections can only be tightened.
• Every overwrite can be undone. Each text edit or restore saves the previous body first (newest 30 kept). Use list_file_versions and restore_file_version, or the history panel in the app. Title and notes changes are not versioned.
• Sharing is deliberate. Sharing makes the original file reachable by link (no copy). Every share needs confirm_share: true; without it nothing changes. list_shared_files shows everything shared.
• Searching one folder. Pass zone_ids to search. Every result names its folder, and an unscoped search warns when results come from several folders.
• Binary uploads take three steps: upload_file → PUT the bytes to the returned URL within 5 minutes → complete_upload. Unfinished uploads are removed after 30 minutes.
• Citing. Cite one passage with its result url (it links to the page or passage); cite a whole document with its file id. page is present for PDFs and lineStart for text with line data.

Words we use

File

Any item in your vault: note, document, PDF, image or web clip.

Folder

A zone. Tools take its id as zone_id.

Share link

A public URL for one file. Older tool names call this a "foundation".

Post

A file with a reply thread.

Thread

A conversation with the BlinkVault assistant (chat_* tools). The assistant can edit files when the connection has write access; its edits are versioned too.

Available tools

Generated from the server's own tool definitions. Read-only tools work on every plan; the rest need Plus or Pro and a connection with write access.

Read-only — never change your vault

• search Search vault Read-only · All plans · vault:read

  Ids: Optional `zone_ids` from list_zones. Pass a result `id` to fetch.

• fetch Fetch vault item Read-only · All plans · vault:read

  Ids: A result `id` from search: a passage id returns that passage, a file id the whole document.

• get_file Get file details Read-only · All plans · vault:read

  Ids: `file_id` from search, list_files or upload_file.

• get_sharing Get sharing details Read-only · All plans · vault:read

  Ids: `file_id`.

• list_tags List tags Read-only · All plans · vault:read

  Ids: None.

• get_job_status Get import status Read-only · All plans · vault:read

  Ids: `job_id` from start_ingestion_job.

• list_jobs List import jobs Read-only · All plans · vault:read

  Ids: None.

• hybrid_search Advanced search Read-only · All plans · vault:read

  Ids: Optional `zone_ids` from list_zones. Pass a result `chunkId` to fetch_document_context.

• fetch_document_context Read surrounding text Read-only · All plans · vault:read

  Ids: `chunk_id` = a passage id from search / hybrid_search.

• traverse_entity_relations Explore connections Read-only · All plans · vault:read

  Ids: None (takes a name).

• list_foundation_replies List post replies Read-only · All plans · vault:read

  Ids: `foundation_file_id` = the post file id.

• list_files List files Read-only · All plans · vault:read

  Ids: Optional `zone_ids` from list_zones.

• get_capabilities What can I do here? Read-only · All plans · vault:read

  Ids: None.

• list_zones List folders Read-only · All plans · vault:read

  Ids: Returns the folder ids other tools take as `zone_id`.

• list_file_versions List file versions Read-only · All plans · vault:read

  Ids: `file_id`. Returns version ids for restore_file_version.

• list_shared_files List shared files Read-only · All plans · vault:read

  Ids: None.

• chat_list_sessions chat_list_sessions Read-only · All plans · vault:read

  Ids: None.

• chat_history chat_history Read-only · All plans · vault:read

  Ids: `session_id` from chat_list_sessions.

Add something new — never overwrite

• start_ingestion_job Import from cloud storage Adds · Plus & Pro · vault:write

  Changes: Imports files from a connected cloud account into the vault. Undo: Delete imported files in the app.

  Ids: Returns a `job_id` for get_job_status.

• upload_file Add file to vault Adds · Plus & Pro · vault:write

  Changes: Creates a new private file. Binary files need complete_upload after the PUT. Undo: Delete the file in the app.

  Ids: Optional `zone_id` from list_zones (an unknown id is an error, never a silent fallback).

• retry_file_processing Retry file processing Adds · Plus & Pro · vault:write

  Changes: Re-runs AI analysis and search indexing for one file. Undo: Not needed (re-derives data from the file itself).

  Ids: `file_id`.

• create_foundation_post Create post Adds · Plus & Pro · vault:write

  Changes: Creates a post (new note or existing file). Private unless confirm_share is set. Undo: Set visibility private with edit_file; delete in the app.

  Ids: Optional `file_id` of an existing file.

• attach_reply Reply to post Adds · Plus & Pro · vault:write

  Changes: Adds a reply to a post; the BlinkVault assistant may answer note replies. Undo: Delete the reply in the app.

  Ids: `foundation_file_id` = post file id; child ids per `kind`.

• create_zone Create folder Adds · Plus & Pro · vault:write

  Changes: Creates a folder (returns the existing one if the name is taken). Undo: Delete the folder in the app.

  Ids: Returns the new `zone_id`.

• complete_upload Finish binary upload Adds · Plus & Pro · vault:write

  Changes: Finishes a binary upload and starts processing. Undo: Delete the file in the app.

  Ids: `file_id` returned by upload_file.

• chat_send chat_send Adds · Plus & Pro · tools:write

  Changes: Sends a message to the BlinkVault assistant. The assistant can itself edit files when this connection has write access. Undo: Assistant edits are saved as versions: list_file_versions + restore_file_version.

  Ids: Optional `session_id` from chat_list_sessions; optional `zone_id`.

Change existing data

• edit_file Edit file Changes · Plus & Pro · vault:write

  Changes: Renames, sets notes, edits the text (replace, find/replace or append), moves to a folder, or changes sharing. Undo: Text edits save the previous body as a version (restore_file_version). Title/notes are not versioned. Sharing: set visibility private.

  Ids: `file_id`; optional `zone_id` from list_zones.

• share_file Share file by link Changes · Plus & Pro · vault:write

  Changes: Makes the ORIGINAL file reachable by anyone with the link (no copy). Requires `confirm_share: true`; without it nothing changes and you get a preview. Undo: edit_file with visibility private revokes the link.

  Ids: `file_id`.

• update_zone_settings Update folder settings Changes · Plus & Pro · vault:write

  Changes: Renames a folder or tightens its protections. Over MCP protections can only be tightened; loosening (unlocking, re-enabling sharing) is done in the app. Undo: Rename back; loosen protections in the app.

  Ids: `zone_id` from list_zones.

• move_file Move file to folder Changes · Plus & Pro · vault:write

  Changes: Moves one file into another folder. Undo: Move it back with move_file.

  Ids: `file_id` and `zone_id` from list_zones.

• restore_file_version Restore file version Changes · Plus & Pro · vault:write

  Changes: Replaces the current body with an earlier version. Undo: The current body is saved as a version first, so a restore can be undone.

  Ids: `file_id` and `version_id` from list_file_versions.

Renamed or replaced (old names keep working until 2027-01-18): list_my_foundations → list_files, create_foundation → share_file, get_foundation → get_sharing, edit_foundation → edit_file, search_vault → search, retrieve_for_rag → search.

Security & limits

• Sign-in connections use OAuth 2.1 with PKCE. Access tokens last one hour, are bound to this server only, and refresh tokens rotate on every use. See and revoke signed-in apps in Connected apps; revocation takes effect on the app's next request.
• Tokens are opaque, 256-bit random strings. Only their SHA-256 hash is stored — the plaintext is never recoverable after creation.
• Every call is logged (tool, status, latency, deny reason). You can revoke a token instantly above; revocation propagates to the validation layer in seconds.
• Tenant isolation is enforced server-side: a token can only access the issuing user's vault, regardless of arguments passed.
• Anomaly detection runs every 5 minutes and flags burst usage, repeated denials, or scope-mismatch patterns. Excessive abuse may auto-lock a token.
• Default token lifetime is 30 days (configurable 1-365). Rotate regularly; never commit tokens to a repo or share them across machines.

Troubleshooting

• 401 Unauthorized: token is missing, malformed, expired, or revoked. Issue a new one above.
• Scope mismatch (JSON-RPC error -32001): the token lacks the scope required by the tool. Re-issue with broader scopes (e.g. add vault:write).
• Tool not found: the client is on an older protocol or the tool was deprecated. Re-run tools/list.
• Empty results: if your vault was just connected, give the AI pipeline a few minutes to index new files before querying.
• Still stuck? See Support.