hypervault-mcp

MCP server for HyperVault — lets any MCP-capable agent save artifacts to a user's vault and claim vanity subdomains.

Built with FastMCP.

Hosted endpoint: https://mcp.vault.cool/mcp (Streamable HTTP) — no install needed, just point your MCP client at it with your own API key. See Auth & rate limits for the header format.

Install & run

pip install -e .          # from this directory (or: uv pip install -e .)

export HYPERVAULT_API_KEY=hv_...            # create one in the web dashboard (/vault)
export HYPERVAULT_API_URL=https://hypervault.store   # optional; defaults to hypervault.store

hypervault-mcp                                # STDIO (local agents)
hypervault-mcp --transport http --port 8787   # HTTP (web agents)

Authentication differs by transport — see Auth & rate limits below.

Related MCP server: hashnet-mcp

Tools

Plus the hypervault://help resource with agent-facing usage notes.

Memories are owner-only: they power the Memory Control Panel at /vault/memory and are never rendered on public pages.

Mutable artifacts (a living document)

Artifacts are immutable by default: a save is permanent, and re-saving the same content just returns the existing link. Save with mutable=True to get a document you can iterate on in place — its URL never changes, and every write is kept as a git commit you can list and revert to:

saved = save_to_hypervault(content="<h1>v1</h1>", title="Notes", mutable=True)
read_artifact(saved["slug"])                       # -> current source + head version
write_artifact(saved["slug"], "<h1>v2</h1>", message="expand intro")
artifact_history(saved["slug"])                    # -> the commit chain, newest first

read_artifact → edit → write_artifact is the iteration loop; to revert, read an old version's content (read_artifact(ref, version=...)) and write it back. The write tools are owner-scoped (the API key resolves to its owner), so a mutable artifact is read and written privately even when the page is public.

Artifact groups (multi-file projects)

Use an artifact group instead of save_to_hypervault when a project needs more than one file — separate markup, styles, and script(s) that reference each other normally, like a tiny JSFiddle. A group always runs/previews as a container at https://hypervault.store/g/{slug} — a minimal editor/preview UI similar to JSFiddle — routed through a required root index.html.

group = create_artifact_group(
    files=[
        {"path": "index.html", "content": "<link rel='stylesheet' href='style.css'><script src='app.js'></script>"},
        {"path": "style.css", "content": "body { font-family: sans-serif; }"},
        {"path": "app.js", "content": "console.log('hello from the group')"},
    ],
    title="My Widget",
)
read_artifact_group(group["slug"])                                   # -> current files + metadata
add_artifact_group_item(group["slug"], "extra.js", "// more code")   # add a new file
edit_artifact_group_item(group["slug"], "style.css", "body { color: red; }")  # replace a file's content
remove_artifact_group_item(group["slug"], "extra.js")                # remove a file (not index.html)
list_artifact_groups()                                               # browse everything saved
delete_artifact_group(group["slug"])                                 # permanently delete the group

Validation runs locally before any network call, so bad input never reaches the backend:

• Exactly one root file at path index.html — the entry point the run/preview container routes through. A nested one like public/index.html does not count.

• Paths must be relative, use / as the separator, contain no .. segments, and only [A-Za-z0-9._/-] characters.

• Extensions are limited to .html, .css, .js, .jsx.

• At most 50 files; 256 KB per file; 1 MB total.

• Paths must be unique (case-insensitively).

• The root index.html can't be removed with remove_artifact_group_item — edit its content instead, or delete the whole group.

Universal task boards (shared work lists)

A task board is a shared, versioned task list that an agent and the user work from together. One call creates both halves: a JSON data artifact (tasks-{project}) the agent syncs through, and an interactive board page (taskboard-{project}) the user opens to watch and steer the work live. Every write is an artifact version (audit trail + rollback), writes are optimistic-concurrency-safe, and claims are locks, so several agents can share one board without collisions.

board = create_task_board(
    title="Eurorack choir firmware",
    tasks=[
        {"id": "epic-1", "title": "Firmware", "type": "epic"},
        {"title": "Bring up I2S clocking", "parent": "epic-1", "priority": "high"},
    ],
)
project = board["project"]
board["board"]["url"]        # <- hand this to the user; it's the living UI

tasks = tasklist_get(project)["tasklist"]["tasks"]
task_claim(project, tasks[1]["id"], agent_name="claude-code:session-abc")
task_update(project, tasks[1]["id"], progress=50, note="I2S clock locked at 48 kHz")
task_complete(project, tasks[1]["id"], note="landed in PR #12")

tasklist_get(project, since_version=12)   # -> {"unchanged": true, ...} when nothing moved
tasklist_summary(project)                 # -> counts, progress, epics, claims

The protocol agents should follow (it's also spelled out in hypervault://help, so a connected agent reads it without being told):

• Read at session start, and re-poll with since_version at tool boundaries — that's how the user's steering from the board page reaches you mid-task.

• Claim deliberately. Prefer tasks assigned to you or unassigned. A live foreign lock fails with a 409 naming the holder; force is only for a holder who is clearly gone (expired locks need no force). Locks last 60 minutes by default, 24 h max, and re-claiming your own task renews it.

• Push every meaningful change immediately — the user's board polls the same list, and a stale board means they're steering blind.

• Send expected_version on writes. A version conflict comes back as {conflict: true, latest, error} — and latest is the whole fresh list, so the tools return that payload rather than collapsing it into an error message. Re-apply your change on top of latest; don't overwrite.

• Map both ways via metadata.externalId to keep a native todo list and the board in sync.

Statuses are todo | in_progress | blocked | review | done | cancelled; priorities are low | medium | high | critical. Marking a task done (either tool) releases the lock, and a done task can't be re-claimed. Task writes return the whole list for convenience — on a large board that's token-heavy, so reach for tasklist_summary and since_version polling instead.

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "hypervault": {
      "command": "hypervault-mcp",
      "env": {
        "HYPERVAULT_API_KEY": "hv_your_key_here"
      }
    }
  }
}

Running under greywall (sandboxed agents)

The server is single-host on purpose: every tool call — including extract_source_prompt, which resolves artifact URLs through the backend's /api/extract — goes to the API origin only. That means it works inside deny-by-default sandboxes like greywall with exactly one domain allowed:

export HYPERVAULT_API_KEY=hv_...
greywall --profile claude,python --settings ./greywall.json -- claude

Then allow the API host (hypervault.store, or your HYPERVAULT_API_URL) in the greyproxy dashboard. The greywall.json template also marks HYPERVAULT_API_KEY as a secret, so the sandboxed agent only ever sees a placeholder — greyproxy substitutes the real key into the X-HyperVault-Key header outside the sandbox. Full guide: docs/greywall.md.

Auth & rate limits

Keys are minted (and revoked) in the web dashboard's Vault → Agent API keys panel. This MCP server never stores or looks up keys itself — it forwards whatever key you give it straight to the real HyperVault backend (hypervault.store), which is the only place that ever validates one (it stores just a salted SHA-256 hash and enforces 60 requests/minute per key).

How the key gets there depends on the transport:

• STDIO (hypervault-mcp, no --transport http) — a single trusted local process. The key comes from the HYPERVAULT_API_KEY environment variable, set once when you start the server (as in Install & run above).

• HTTP (hypervault-mcp --transport http, and the hosted Vercel deployment) — a single server can be shared by many callers, so every request must carry its own key, sent per-call as either:

  • Authorization: Bearer hv_... (standard, recommended for MCP clients), or

  • X-HyperVault-Key: hv_...

  There is no shared fallback key for HTTP: a request with neither header is rejected with an "Authentication required" tool error before any call reaches the backend, even if the server process happens to have HYPERVAULT_API_KEY set in its own environment. Listing the available tools (tools/list) doesn't require a key — no user data is involved — but every tool call does. Configure your MCP client to send your key as a header on the hosted endpoint, e.g. for a mcp.json-style config:

  {
    "mcpServers": {
      "hypervault": {
        "url": "https://mcp.vault.cool/mcp",
        "headers": { "Authorization": "Bearer hv_your_key_here" }
      }
    }
  }

  https://mcp.vault.cool/mcp is a custom-domain alias for the same deployment as https://hypervault-mcp.vercel.app/mcp — the two are interchangeable and always serve identical code.

Tests

pip install -e ".[test]"
pytest

The suite (tests/) covers the request-shaping logic of every tool, the _client/_request HTTP layer (mocked with respx — no real network calls), the extract_source_prompt preferred/legacy fallback chain, the task-board tools (body shaping, the empty-patch and blank-agent_name guards, and the 409 conflict payload coming back intact instead of as an exception), and — most importantly — the per-request auth model: header parsing, the STDIO-vs-HTTP key resolution split, and full end-to-end requests against the real ASGI app proving an unauthenticated tools/call is rejected even when an operator HYPERVAULT_API_KEY is set in the environment.

Smoke test

With the web app running locally (npm run dev in the repo root) and a key exported:

python - <<'PY'
from fastmcp import Client
from hypervault_mcp.server import mcp
import asyncio

async def go():
    async with Client(mcp) as client:
        tools = await client.list_tools()
        print("tools:", [t.name for t in tools])
        result = await client.call_tool("save_to_hypervault", {
            "content": "<h1>Hello from an agent</h1>",
            "title": "MCP smoke test",
        })
        print(result)

asyncio.run(go())
PY

Task boards need a backend running hypervault ≥ PR #128:

python - <<'PY'
from fastmcp import Client
from hypervault_mcp.server import mcp
import asyncio

async def go():
    async with Client(mcp) as c:
        board = (await c.call_tool("create_task_board", {
            "title": "MCP smoke", "tasks": [
                {"id": "epic-1", "title": "Epic", "type": "epic"},
                {"title": "Child task", "parent": "epic-1"},
            ]})).data
        p = board["project"]                          # board["board"]["url"] is the human page
        lst = (await c.call_tool("tasklist_get", {"project": p})).data["tasklist"]
        tid = next(t["id"] for t in lst["tasks"] if t["parent"] == "epic-1")
        await c.call_tool("task_claim", {"project": p, "task_id": tid, "agent_name": "smoke-test"})
        await c.call_tool("task_update", {"project": p, "task_id": tid, "progress": 50, "note": "halfway"})
        done = (await c.call_tool("task_complete", {"project": p, "task_id": tid, "note": "done"})).data
        assert done["summary"]["byStatus"]["done"] == 1
        assert (await c.call_tool("tasklist_get", {"project": p,
            "since_version": done["summary"]["version"]})).data["unchanged"] is True
        print("task board:", board["board"]["url"])

asyncio.run(go())
PY