MCP server

The Personify MCP server exposes your vault as read-only context for Model Context Protocol clients. It has two local transports:

• stdio, launched with vault mcp, for Claude Desktop and similar clients.
• streamable HTTP, mounted at /mcp on FastAPI and gated by the UI's MCP Start/Stop control.

What's exposed

• 13 tools — search, semantic_search, timeline, get_item, recent_items, recent_runs, list_sources, list_accounts, stats, plus 4 graph tools. See tools.
• 6 resources — vault://stats, vault://recent, vault://sources, vault://item/{id}, vault://entity/{id}, vault://export/{id}. See resources.

Claude Desktop over stdio

Edit your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "personify": {
      "command": "vault",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop. The personify server should show as connected and the tools should be visible in the tool picker.

If vault is not on the PATH that Claude Desktop sees, use the absolute path inside the repo virtualenv:

{
  "mcpServers": {
    "personify": {
      "command": "C:\\Users\\you\\personify\\.venv\\Scripts\\vault.exe",
      "args": ["mcp"]
    }
  }
}

UI-gated HTTP MCP

When npm start is running, the FastAPI app also has a streamable HTTP MCP transport mounted at /mcp. It is closed by default.

To open it:

1. Open the Personify UI.
2. Go to Settings.
3. Click the MCP Start control.

Status endpoint:

curl http://127.0.0.1:18765/api/mcp/status

When enabled, local MCP clients can target:

http://127.0.0.1:18765/mcp

When stopped, the mount returns 503. A plain browser request to /mcp is not a health check; use /api/mcp/status or an MCP client.

Multiple vaults

Register one stdio entry per vault if you want separate clients:

{
  "mcpServers": {
    "personify-personal": {
      "command": "vault",
      "args": ["mcp"]
    },
    "personify-code": {
      "command": "vault",
      "args": ["--vault", "code-corpus", "mcp"]
    }
  }
}

For the UI-gated HTTP transport, the active vault is the one selected in the UI vault switcher.

Environment variables

Most users do not need to set anything. The server picks up the same PERSONIFY_* env vars as the CLI.

Security model

Personify's MCP surfaces are intended for local, trusted use.

1. The stdio server is started by a local MCP client as your user.
2. The HTTP transport is off by default and can be toggled in the local UI.
3. The server inherits your filesystem and database privileges.
4. Anything the vault can read, the connected LLM can read.

Do not expose /mcp to an untrusted network without authentication and network controls in front of FastAPI.

Troubleshooting

The server is not connecting in Claude Desktop. Check that vault is on the PATH Claude sees. On Windows, prefer the explicit .venv\Scripts\vault.exe path.

The UI says MCP is on, but /mcp returns 404 or 503 in a browser. Use /api/mcp/status. The MCP mount is a protocol endpoint, not a web page. 503 means the UI gate is closed; enabled: true in the status payload means the gate is open.

Tools call but return errors. Run vault stats in the same shell environment your MCP client uses. The MCP server uses the same Postgres connection string as the CLI.

Logs. The stdio server writes logs to stderr. Stdout is reserved for JSON-RPC framing. Anything written to stdout that is not a valid frame will break the client.

semantic_search returns nothing. You probably have not run vault embed yet. The full-text search tool works without embeddings; semantic search needs vectors populated.

Where next

• Tools — full reference for all 13 tools.
• Resources — the six vault:// URIs.
• Architecture — how the data the MCP server reads got there.