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.
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.
Settings → Connectors → Add custom connector. Paste the URL.
https://vault.martzmakes.com/mcp
Settings → Connectors → Add connector. Paste the URL and approve the magic-link email.
https://vault.martzmakes.com/mcp
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
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
Run once in any terminal. Claude Code opens the consent screen.
claude mcp add --transport http vault https://vault.martzmakes.com/mcp
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" }
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.
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.
| Tool | What it is for | Scope |
|---|---|---|
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 |
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.
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.
| Code | When |
|---|---|
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 |
Email support@martzmakes.com if a client won't connect or something looks wrong. support@martzmakes.com