Home / Docs / Agents / Claude Desktop

Connect Claude Desktop to your BoxOwl vault

Five steps: create a token in the BoxOwl app, drop the daemon into Claude Desktop's MCP config, restart Claude. After that every conversation can read your vault.

Step 1 — Create an agent token

Open the BoxOwl Android app. Go to Settings → AI Agent Connections → New. Name the token "Claude Desktop on <machine>", pick the scopes you want Claude to have (a starter set: vault:read, profile:read, agent:query), and tap Generate. The plaintext token is shown exactly once — copy it now.

Token format: bxusr_<8-hex>_<32-char-secret>. See Agent tokens for the full scope vocabulary.

Step 2 — Install the local daemon

Claude Desktop talks to BoxOwl through the local boxowl-daemon binary over the MCP stdio transport. Install via Homebrew (macOS / Linux): 

brew install boxowl/tap/boxowl-daemon

Or download the latest release from github.com/BoxOwl-Me/daemon/releases and put the binary somewhere on your PATH.

Step 3 — Add the MCP server to Claude Desktop

Edit Claude Desktop's MCP config. The file lives at:

Add a boxowl entry under mcpServers: 

{
  "mcpServers": {
    "boxowl": {
      "command": "/opt/homebrew/bin/boxowl-daemon",
      "args": ["mcp"],
      "env": {
        "BOXOWL_AGENT_TOKEN": "bxusr_a1b2c3d4_xT8mPq5KwR9NhL2vYzD3sB6FjUcW1AeXgHnM"
      }
    }
  }
}

Replace the command path with wherever your boxowl-daemon binary lives (which boxowl-daemon shows it). Replace BOXOWL_AGENT_TOKEN with the token you copied in Step 1.

Step 4 — Restart Claude Desktop

Quit Claude Desktop fully (Cmd+Q on macOS) and reopen it. The MCP server only loads at startup; closing the window isn't enough.

Once Claude is back, type /mcp in any conversation. You should see boxowl listed as a connected server with a tool list ending in boxowl_get_item, boxowl_search, etc.

Step 5 — Test a query

Ask Claude something that requires your vault. For a starter set of scopes: 

You: What's my shipping address?
Claude: [reads your vault via the boxowl MCP server] Your shipping
        address on file is <your address>. Want me to copy it?

Confirmation-gated writes (saving credentials, payments) prompt you before they run. The agent-token docs describe the scope vocabulary that controls what Claude can do.

Manage the connection

In the BoxOwl app go to Settings → AI Agent Connections to see when this token last ran, what it touched, or to revoke it. Revocation is immediate — Claude's next call after revoke gets a 401 and the agent stops working.

Premium users can have unlimited agent tokens; Free users get one. See pricing for the tier breakdown.