gvmcp is the MCP server that exposes memory_save and memory_search to the model and calls gvsvd with your vault session. The OpenAPI file in the repo describes the same REST contract for ChatGPT Custom GPT Actions, Gemini function calling, and other HTTP clients—not a separate API surface. The hosted custom connector is the path where Anthropic’s cloud calls your HTTPS MCP URL—not the same as local stdio MCP in Claude Desktop.
1. Two approaches (not interchangeable)
Local / IDE: Claude Desktop, Cursor, or Claude Code runs gvmcp on your machine (stdio) or uses npx mcp-remote to a URL you open. Hosted connector: you register one remote MCP URL under Customize → Connectors; Anthropic’s servers call it from the internet. That requires public HTTPS to your edge (for example Tailscale Funnel to the port your nginx forwards to)—tailnet-only DNS is not enough for claude.ai.
2. Unlock the vault and keep a session bearer
Before tools work, gvsvd must accept your vault. Use gvctl unlock (or the dashboard flow) and keep the bearer the server expects—often .ghostvault-bearer or GHOSTVAULT_BEARER_TOKEN for gvmcp. If gvsvd restarts and the file is empty, MCP can show “connected” in Claude while /v1/ calls return 401 until you unlock again.
3. Local MCP mode (optional alternative)
For day-to-day development you can skip the hosted connector: configure the MCP client to run gvmcp with GHOSTVAULT_BASE_URL and your bearer, no public URL. This is the usual Cursor / Desktop setup when you do not need claude.ai or the mobile app to reach the same endpoint.
4. Dashboard
The bundled dashboard (when enabled in Docker) gives you a web UI on top of the same API: health, configuration, and shortcuts into vault operations. Edge still fronts /api, /mcp-<token>/, and the dashboard path per your compose and nginx template.
5. Anthropic custom connector (hosted MCP)
In Claude (claude.ai or Desktop): Customize → Connectors → Add custom connector. Register the MCP base URL for your deployment. With Ghost Vault’s edge, that URL includes a secret path token from GV_MCP_PATH_TOKEN in .env, for example https://YOUR-PUBLIC-HOST/mcp-<token>/ (trailing slash behavior is handled at the edge). Do not publish this URL in public tickets—it is a capability URL. POST must succeed from the public internet so Anthropic’s infrastructure can start the MCP session.
Keep three layers straight: (1) path token in the URL, (2) vault session bearer on the server for gvmcp → gvsvd, (3) optional OAuth token for Claude → gvmcp (next section). Full table: Three different secrets.
6. OAuth (optional)
You can run path token only (no OAuth) if introspection is unset—connector Advanced OAuth may stay empty. If you add an IdP (Auth0, ZITADEL, etc.), gvmcp validates access tokens (often RFC 7662 introspection) while gvsvd still relies on the vault bearer. claude.ai may expect OAuth metadata and authorize flows on the MCP host; Ghost Vault’s facade proxies /authorize and /token to your IdP where needed—see
OAuth on gvmcp.
7. Save memory (tool)
In chat, with the connector enabled, Claude calls memory_save to persist a chunk into your vault (namespace from defaults or tool args). You should see confirmation in the thread and the new row available for retrieval.
8. Search memory (tool)
memory_search runs hybrid retrieval (vector + text + fusion) over stored chunks. Use it in the same conversation to ground answers in what you have saved.
9. Inspect chunks
Use the UI or API to open a chunk: abstract and body, metadata, and integrity fields depending on your schema. This helps debug what the model actually stored and why search ranks results as it does.
10. OpenAPI: HTTP tools (ChatGPT, Gemini, custom clients)
Ghost Vault ships a machine-readable contract at openapi/openapi.example.yaml (copy to openapi/openapi.yaml in your tree). Step 1 for every HTTP integration: expose gvsvd (usually via Compose edge) on a public https:// URL using a tunnel or reverse proxy (ngrok, Cloudflare, Tailscale Funnel—not tailnet-only Serve for vendors that call you from the internet). Step 2 is product-specific: import the spec into ChatGPT Actions or wire Gemini to the same operations and request bodies.
Point servers[0].url at the HTTP origin clients will use—the same base as GHOSTVAULT_BASE_URL for gvctl / gvmcp. With the default edge stack, REST is under a single prefix, for example https://YOUR-PUBLIC-HOST/api (no trailing slash; paths in the file remain /v1/… so calls become /api/v1/… at the wire). If you tunnel gvsvd without edge, match that layout and adjust health checks accordingly.
Authentication is Authorization: Bearer <token> for protected routes. After POST /v1/vault/unlock, use the session_token from the response (or gvctl unlock -token-only). Remote hosts must be able to reach that origin and TLS must be valid for production vendors.
Smoke test from a network that is not your LAN (or use the tunnel’s public hostname):
curl -sS "https://YOUR-PUBLIC-HOST/api/healthz"
Unlock (encrypted vault) example—then copy session_token and use it as the Bearer for POST /v1/retrieve, POST /v1/memory/…, and the other secured operations in the spec:
curl -sS -X POST "https://YOUR-PUBLIC-HOST/api/v1/vault/unlock" \
-H "Content-Type: application/json" \
-d '{"password":"YOUR_PASSPHRASE"}'
Plaintext vaults can mint a scoped token with POST /v1/tokens/actions in some modes—see
Get a Bearer token in OPENAPI.md. Keep vault_id and user_id consistent in tool payloads so retrieval stays scoped; refresh the spec and vendor config if your tunnel URL changes (free ngrok URLs often rotate when you restart the agent).
Full checklists, Funnel vs Serve, and troubleshooting: OPENAPI.md ·
deploy.md (expose gvsvd over HTTPS).
Checklist & docs
Hosted connector: public HTTPS, edge with GV_MCP_PATH_TOKEN, gvmcp + vault bearer, curl health check from outside your LAN if possible. OpenAPI / Actions: servers[0].url + Bearer, then ChatGPT or Gemini per section 10. Not working: re-read
Claude-connector.md
and
DEPLOY.md
(Funnel, tunnels, edge ports). Same connector syncs to claude.ai, Desktop, and the Claude app once you sign in to the same account.