Connect Claude and other AI agents

What you need

• PassSumo installed in /Applications, on macOS 27 or later.
• A database. Agent access is set up per database.
• An MCP client: Claude Code, Cursor, Codex, Claude Desktop, or any client that can start a local stdio server.

Step 1. Turn on agent access for a database

1. Open and unlock the database in PassSumo.
2. Open Settings (Cmd+,) and go to Agent access.
3. Turn on Allow AI agent read access. It is off until you do.
4. Under Allowed folders, tick the folders the agent may see. An entry outside them comes back as not_found, as if it did not exist.
5. Choose a Grant duration. A grant always ends by itself after that time.

A database that has never had agent access turned on must be unlocked once in PassSumo, with the setting on, before an agent can ask for it.

Step 2. Install psumo with a symlink

The psumo program lives inside the app, at /Applications/PassSumo.app/Contents/MacOS/psumo. Point your tools at a symlink to it, not at the bundle itself, so the setup survives app moves and updates. Run:

mkdir -p ~/.local/bin && ln -sf /Applications/PassSumo.app/Contents/MacOS/psumo ~/.local/bin/psumo

Settings → Agent access shows the same line with your real paths and a Copy install command button.

Do not copy the file. PassSumo checks the code signature of the program that connects to it, and a copied psumo fails that check (unverified_peer). A symlink resolves to the real binary and works.

Check that it answers (PassSumo must be running):

~/.local/bin/psumo ping

It prints pong.

Step 3. Add PassSumo to your client

Claude Code

Register the server once:

claude mcp add psumo -- ~/.local/bin/psumo mcp

The shell expands ~ before Claude Code stores the command. Settings → Agent access also has a Copy MCP command button with your real path.

Claude Desktop

Add a server to Claude Desktop's configuration file (claude_desktop_config.json), using the absolute path of the symlink, with mcp as its only argument:

{
  "mcpServers": {
    "psumo": {
      "command": "/Users/YOUR-NAME/.local/bin/psumo",
      "args": ["mcp"]
    }
  }
}

Replace YOUR-NAME with your macOS user name, then restart Claude Desktop.

Any other MCP client

PassSumo speaks MCP over stdio, one JSON message per line, and prints nothing else on standard output. Configure your client to start this command:

/Users/YOUR-NAME/.local/bin/psumo mcp

No environment variables or extra flags are needed; mcp takes no arguments.

Step 4. Approve the first request

Ask your agent for a password. PassSumo shows an approval request that names the database and the reason the agent gave; every call must carry one. Click Allow… and confirm with Touch ID or your Mac password.

If PassSumo is not running, psumo starts it in the background. You never have to add a timeout on the agent's side: PassSumo ends an unanswered request itself.

Step 5. Try it from Terminal

You can test the whole path without an agent. Find an entry (metadata only, no secrets):

~/.local/bin/psumo find Test

Replace Test with part of an entry's title. The first value on each line is the entry id. Then reveal one field:

~/.local/bin/psumo reveal <id> --field password

One field prints its raw value; several fields print JSON.

What the agent can and cannot do

• Four tools: list_databases, list_groups, find_entries and reveal_entry. Every call needs a reason, which you see when you approve.
• Searching returns metadata only. find_entries gives titles and ids, never secret values.
• Revealing returns the secret. reveal_entry returns the fields it names: username, password, totp, url, notes or custom:<name>. The values are returned to the agent.
• Read by default. At each approval, on the Mac, the person chooses Read or Read and write. Write only means adding a new entry in an allowed folder (add_entry). No tool changes, moves or deletes an existing entry.
• Only allowed folders. Everything else is invisible to the agent.

Duration and revoking access

• A grant lasts for the duration you chose, is never extended by later requests, and also ends when PassSumo quits. A plain lock does not end it; use the menu command below.
• In Settings → Agent access, Revoke ends the current grant, End session ends one listed grant, and Revoke all ends every grant.
• The File menu's Lock & Revoke Agent Access locks the database and ends its grant in one step.
• Turning off Allow AI agent read access stops new requests for that database.

Troubleshooting

• app_not_running or db_not_open — PassSumo is not running, or the database is not open. Open it with

  open -a PassSumo "<path to the .psum file>"

  and retry. Agents should use the path you give them and never search the disk for databases.
• disabled — agent access is off for that database. Turn it on in Settings → Agent access.
• not_found — the entry is outside the allowed folders, or the id is wrong.
• denied — the request was declined.
• timeout — nobody answered in time. Ask again.
• unverified_peer — psumo is a copy, not a symlink into the app. Re-run the install command from Step 2.
• The link points at an old location after you moved the app — run the install command again to re-point it.

Still stuck? The feedback form reaches the person who writes the code. Common questions are in the FAQ.