Docs

Connect any MCP client to your vault.

Everything an AI client (or the person wiring one up) needs: the endpoint, how auth works, every tool and its scope, the limits, and what to ask once connected.

Prefer plain text? https://vault.martzmakes.com/llms.txt has the same facts in one file.

Endpoint

One MCP endpoint.

https://vault.martzmakes.com/mcp

Streamable HTTP, protocol version 2026-07-28.

Send Accept: application/json, text/event-stream on every request; the server replies in whichever of the two the request needs.

Discovery documents: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.

Connect a client

Any MCP client, one URL.

Claude

claude.ai · desktop

Settings → Connectors → Add custom connector. Paste the URL.

https://vault.martzmakes.com/mcp

ChatGPT

chatgpt.com

Settings → Connectors → Add connector. Paste the URL and approve the magic-link email.

https://vault.martzmakes.com/mcp

OpenAI Dots

chatgpt.com · agents

Add Vault as a ChatGPT connector once. A Dot you message or call uses the same connection, with the same notes.

https://vault.martzmakes.com/mcp

Muse

Meta Muse app

Ask Muse to create a custom connector for this MCP server (remote, streamable HTTP) and approve the sign-in email when it connects.

https://vault.martzmakes.com/mcp

Claude Code

CLI

Run once in any terminal. Claude Code opens the consent screen.

claude mcp add --transport http vault https://vault.martzmakes.com/mcp

Muse Code

CLI

Add to the mcp_servers block of ~/.config/muse/settings.json, then run muse mcp login vault for the consent screen.

"vault": { "transport": "streamable_http", "url": "https://vault.martzmakes.com/mcp" }
Authentication

OAuth 2.1. No API keys to leak.

Dynamic client registration and PKCE. Sign-in is an emailed magic link to an allow-listed address — no password, ever.

A client registers dynamically or presents a client metadata document (CIMD) URL as its client id; either way it ends up with the same OAuth 2.1 flow.

Refresh tokens rotate on use: each refresh returns a new refresh token, and the one you spent stops working.

Scopes: mcp:read, mcp:tools. The Scope column below is advisory today: every mcp:tools token can call every tool; per-client scopes arrive with M7.

Tools

Thirty tools, each read or write.

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. Attachments (non-note files) list, download, upload and delete the same way, gated by plan.

ToolWhat it is forScope
list_directory Browse one folder: the subfolders and notes directly inside it. read
read_note 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. read
write_note Create or overwrite a Markdown note at a path. write
append_note Add text to the end of a note, or of one heading's section, without resending the note. write
edit_note Replace an exact passage in a note without resending the note. write
move_note Rename or move a note to a new path and learn which notes still link to the old path so you can update them. write
delete_note Delete a note by path (old versions are kept for 30 days; there is no restore tool yet). write
get_index_status Tell whether a note's latest saved version is searchable yet. read
complete_task Tick (or with done: false, untick) one checkbox task by note path and the line list_tasks reported. write
list_notes 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. read
list_tasks 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. read
list_tags See every tag in the vault with how many notes carry it, most used first; pass a tag to list_notes to open them. read
search_text Find notes by keyword, or by exact phrase when the query is wrapped in double quotes, with an excerpt, score and url per hit. read
semantic_search Find passages by meaning when you don't know the exact words. read
get_backlinks See which notes link to a given note. read
get_outgoing_links See where a note links to, split into resolved paths and unresolved targets. read
get_related_notes Discover notes related to a given one by shared links, shared tags and semantic similarity, ranked with reasons. read
get_usage 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. read
list_clients See which AI clients and apps currently hold a sign-in to this vault: name, scope, sessions, first and last seen. read
list_vaults List the vaults on this account, with the default one flagged. read
create_vault Create a new vault on this account; the first one becomes the default. write
import_begin Start a zip import by getting a link to upload an Obsidian-vault zip to. write
import_commit Finish a zip import once the upload succeeds, to unpack it in the background. write
export_begin Start a zip export of the whole vault in the background. write
get_job_status Check an import or export job's status and counts, with a download link once an export is done. read
list_jobs List your recent import and export jobs, newest first. read
list_attachments List attachments (non-note files) across the vault, filterable by folder, each with its size, modified time and a download url. read
get_attachment_url Get a 15-minute download link for an attachment, resolved by path or by a bare filename the way Obsidian resolves an embed. read
read_attachment Read a small attachment inline, up to 4 MB: an image block for images, base64 for everything else. read
begin_attachment_upload Start uploading an attachment too large to send inline: a presigned link to upload directly, bound to the file's size and type. write
write_attachment Create or overwrite a small attachment, up to 4 MB, from base64. write
delete_attachment Delete an attachment by path. write
Limits

Fair use by plan.

Index

Writes save immediately; the index catches up.

Files save immediately, but search, links, tags and tasks read from an index that can lag a write by up to a minute.

Call get_index_status to tell whether a note's latest saved version is searchable yet.

Events

Subscribe to changes; Vault pushes them.

Vault implements OpenAI's MCP events contract: events/list, events/subscribe, events/unsubscribe on the same authenticated endpoint, advertised as events: {} in the server's capabilities.

One event, note.changed, fires after a note is created, updated or deleted by any client or by the web app, once the index has caught up. Its payload carries path, kind, title, tags, summary; read the full note with read_note. Subscriptions take path_prefix and tag as filters.

Delivery is a webhook: pass delivery.mode: "webhook", a public HTTPS delivery.url and a whsec_ secret. Vault verifies the callback with a signed challenge before the first event, signs every delivery per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature, X-MCP-Subscription-Id), caps bodies at 256 KiB and never retries a 410 or 413. Events are not replayable yet, so cursor is always null; re-subscribe before refreshBefore to keep a subscription alive.

Errors

Error codes.

CodeWhen
INVALID_PATH the path is absolute, traverses, or is otherwise malformed
NOT_FOUND no note at that path
ETAG_CONFLICT if_match is stale; re-read and retry with currentEtag
DESTINATION_EXISTS move_note's target already exists
HEADING_NOT_FOUND read_note's heading is not in the note
TASK_MISMATCH the line is not a checkbox or its text changed
INVALID_CURSOR the cursor is malformed or from a different query
QUOTA_EXCEEDED the month's allowance, storage, per-file size, or egress fair use is used; resetsAt or limit says where
RATE_LIMITED more than 60 operations in a minute from one client
INDEX_UNAVAILABLE the index could not be loaded; retry shortly
ACCESS_DENIED the tenant's data role refused the request
UPSTREAM_ERROR an AWS service failed; service names it
INVALID_ARGUMENT a rule the schema cannot express (a .md path, a limit of 1 to 200)
VAULT_NOT_FOUND the vault argument matches no vault, or none was given and there's no default to fall back to
VAULT_EXISTS create_vault's name is already used by another vault on this account
PLAN_REQUIRED the plan has no attachment storage at all (Free is text only)
TOO_LARGE read_attachment's attachment is over the 4 MB inline cap; use get_attachment_url instead
Example prompts

What to ask, once connected.

Support

Need help?

Email support@martzmakes.com if a client won't connect or something looks wrong. support@martzmakes.com