# Vault Vault is a persistent, portable Markdown knowledge store that AI clients read and update over MCP, the same notes a person edits directly. ## Endpoint https://vault.martzmakes.com/mcp - streamable HTTP, protocol version 2026-07-28. Discovery documents: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Send Accept: application/json, text/event-stream on every request. ## Authentication OAuth 2.1 with dynamic client registration and PKCE. Sign-in is an emailed magic link to an allow-listed address. Scopes: mcp:read, mcp:tools. A client registers dynamically or presents a client metadata document (CIMD) URL as its client id. Refresh tokens rotate on use: each refresh returns a new refresh token and the spent one stops working. The scope on each tool below is advisory today: every mcp:tools token can call every tool; per-client scopes arrive with M7. ## Tools Most tools take an optional vault argument (an id or name from list_vaults); leave it out to use the account's default vault. Import a zip to seed a vault or export one to back it up; both run as a background job you poll with get_job_status. - list_directory (read): Browse one folder: the subfolders and notes directly inside it. - read_note (read): Read a note: raw is the full file text, content is the body (or one heading's section when heading is given), plus frontmatter, headings, links and a url. - write_note (write): Create or overwrite a Markdown note at a path. - append_note (write): Add text to the end of a note, or of one heading's section, without resending the note. - edit_note (write): Replace an exact passage in a note without resending the note. - move_note (write): Rename or move a note to a new path and learn which notes still link to the old path so you can update them. - delete_note (write): Delete a note by path (old versions are kept for 30 days; there is no restore tool yet). - get_index_status (read): Tell whether a note's latest saved version is searchable yet. - complete_task (write): Tick (or with done: false, untick) one checkbox task by note path and the line list_tasks reported. - list_notes (read): List notes across the vault to orient or inventory: recursive by default, filterable by folder and tag (nested tags included), sortable by path, modified time or title, paged with an opaque cursor, with totals and a url per note. - list_tasks (read): Find checkbox tasks across the vault (open by default, or done, or all), filterable by folder and tag, ordered by note then line, with heading and url. - list_tags (read): See every tag in the vault with how many notes carry it, most used first; pass a tag to list_notes to open them. - search_text (read): Find notes by keyword, or by exact phrase when the query is wrapped in double quotes, with an excerpt, score and url per hit. - semantic_search (read): Find passages by meaning when you don't know the exact words. - get_backlinks (read): See which notes link to a given note. - get_outgoing_links (read): See where a note links to, split into resolved paths and unresolved targets. - get_related_notes (read): Discover notes related to a given one by shared links, shared tags and semantic similarity, ranked with reasons. - get_usage (read): See how much of this month's agent allowance is left and when it resets: plan, agent operations and semantic searches used against their limits, and the per-minute rate limit. - list_clients (read): See which AI clients and apps currently hold a sign-in to this vault: name, scope, sessions, first and last seen. - list_vaults (read): List the vaults on this account, with the default one flagged. - create_vault (write): Create a new vault on this account; the first one becomes the default. - import_begin (write): Start a zip import by getting a link to upload an Obsidian-vault zip to. - import_commit (write): Finish a zip import once the upload succeeds, to unpack it in the background. - export_begin (write): Start a zip export of the whole vault in the background. - get_job_status (read): Check an import or export job's status and counts, with a download link once an export is done. - list_jobs (read): List your recent import and export jobs, newest first. - list_attachments (read): List attachments (non-note files) across the vault, filterable by folder, each with its size, modified time and a download url. - get_attachment_url (read): Get a 15-minute download link for an attachment, resolved by path or by a bare filename the way Obsidian resolves an embed. - read_attachment (read): Read a small attachment inline, up to 4 MB: an image block for images, base64 for everything else. - begin_attachment_upload (write): Start uploading an attachment too large to send inline: a presigned link to upload directly, bound to the file's size and type. - write_attachment (write): Create or overwrite a small attachment, up to 4 MB, from base64. - delete_attachment (write): Delete an attachment by path. ## Limits Free: 500 agent operations a month. Personal: 10,000 agent operations a month. Pro: 50,000 agent operations a month. 60 operations a minute per client on every plan. Humans are never metered: Vault's own web app is never counted against these limits, only AI clients calling tools. ## Events events/list, events/subscribe, events/unsubscribe implement https://developers.openai.com/plugins/build/mcp-events on the same endpoint. One event, note.changed (created, updated, deleted), filtered by path_prefix or tag; payload fields: path, kind, title, tags, summary. Webhook delivery signed per Standard Webhooks; not replayable (cursor is null). ## Example prompts - "What did I decide about authentication for the API project, and where is it written down?" - "List my open tasks under Projects and tick the ones I finished today." - "Which notes link to my onboarding checklist?" - "Summarise everything tagged #meeting from this week." - "Create Daily/2026-10-03.md from yesterday's daily note and carry over the unfinished tasks." - "Find the note where I compared the two laptops and give me the pros list." - "Rename Projects/Old Name.md to Projects/New Name.md and tell me what still links to it." - "What are my most used tags?" - "How much of this month's agent allowance have I used?" - "Which AI clients are connected to my vault right now?" ## Instructions for models This server is one person's Obsidian-compatible Markdown vault: folders of notes with frontmatter, #tags, [[wikilinks]] and checkbox tasks. A tenant may hold several vaults: list_vaults names them; every other tool takes an optional vault (id or name) and otherwise uses the default vault. Orient with list_notes (recursive, filterable by folder or tag, sortable, paged with cursors) or list_directory for one folder. Find things with search_text for words and exact "phrases", or semantic_search for meaning; both return excerpts, scores and a url. There is no generation tool: answer from the excerpts and cite the note paths. Read a note with read_note (raw is the full file; content is the body, or one heading's section). Write with write_note and pass if_match with the etag you read so a concurrent edit is never lost; move_note renames, delete_note removes. To change part of a note use append_note or edit_note instead of resending it. Checkbox tasks: list_tasks finds them (open by default), complete_task ticks one by path and line and, given expect_text, refuses if the line's text changed. Files save immediately, but search, links, tags and tasks read from an index that lags a write by up to a minute; get_index_status reports when it's searchable. Bulk moves: import_begin/import_commit load an Obsidian zip, export_begin packs the vault, get_job_status reports progress. Attachments: list_attachments and list_directory show files; get_attachment_url gives a 15-minute download link, read_attachment returns small images inline; write_attachment and begin_attachment_upload add files on plans that include storage. get_usage shows the month's remaining agent operations and the 60-per-minute rate limit; when a quota is exhausted the error names the reset time. ## Links https://vault.martzmakes.com/docs/ https://vault.martzmakes.com/