psamvault-mcp

v0.4.4 — MCP server for psamvault.

Lets AI agents use your stored credentials without ever seeing their plaintext values. Also integrates with pv-dotenv for runtime credential resolution in your .env files.

Agents installing or repairing this MCP: read docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md before debugging. Common failures are PATH shadowing, corrupt pipx installs, missing absolute paths in client config, expired vault sessions, and mid-session MCP not reloading until restart.

Features

Tools are grouped into three categories. Always start in Entry & Orientation.

🛠 Entry & Orientation

Discover what tools are available and verify the server is running.

Tool	What it does
search_vault_tools	Discovery tool — call this first to find the right tool for your task
get_version	Get the installed server version

🔐 Site Authentication

End-to-end: discover, check, and log into websites.

Tool	What it does
list_vault_sites	List all stored credential sites (names and username hints only)
check_credential_exists	Check if a credential exists for a site
get_username_for_site	Get stored username (never the password)
browser_login	Opens Chromium, navigates to any site, fills credentials directly in the browser — agent never sees them

🔑 API Key Operations

All tools that deal with API keys — discover, use, inject, and protect.

Tool	What it does
list_api_keys	Lists all stored API key names with service hints and project grouping — never returns key values
use_credential	Makes authenticated HTTP requests for you (API keys, bearer tokens, basic auth) — only the HTTP response is returned
run_with_credential	Runs a CLI command with a credential injected via environment variable or stdin — all output redacted of the secret value
scan_and_protect	Scans a project directory for .env files, encrypts secrets into psamvault, replaces plaintext with psamvault:KEY placeholders
export_key_to_mcp_config	Exports a vault API key directly into a client MCP config file (Hermes, Claude, etc.) — auto-verifies HTTP keys before writing
export_key_to_env_file	Exports a vault API key into an agent's .env as an environment variable (default HERMES_HOME/.env) — updates in place, backs up, auto-verifies
verify_api_key	Verifies a stored API key is valid against its provider's API — returns status, provider, and verification result

New in v0.4.6: export_key_to_mcp_config, verify_api_key, and the auto-verifying export gate (verified-before-write for HTTP keys).

Breaking in v0.5.0: capture_stripe_credentials was REMOVED (the Stripe Projects capture flow is gone). Use scan_and_protect for project .env secrets.

New in v0.5.0: export_key_to_env_file — put a vault key into an agent .env as an environment variable (default HERMES_HOME/.env, explicit env_path for other hosts), updating in place with a timestamped backup.

New in v0.4.0: use_credential, run_with_credential, scan_and_protect, list_api_keys, single-process browser architecture (no fragile subprocess daemon), auto-restart on crash.

How it works

Browser login flow (browser_login)

When an AI agent needs to log you into a website, psamvault opens a real Chromium browser, navigates to the site, and fills in the credentials directly inside that browser process.

The agent never sees the credentials. It only sees whether the login succeeded.

Agent: "Log me into kaggle.com"
         ↓
psamvault opens Chromium → navigates to kaggle.com → finds the login page
         ↓
psamvault decrypts credential locally
         ↓
psamvault fills username + password fields directly in the browser
         ↓
If a CAPTCHA appears, psamvault takes a screenshot, pauses automation,
and tells you to solve the CAPTCHA and click Sign in manually
         ↓
Agent receives:
         {
           "success": true,
           "message": "Logged in to github.com successfully.",
           "steps_count": 8,
           "url": "https://github.com/dashboard",
           "captcha_detected": false
         }
         ↓
Browser stays open — you take over from there.
The browser session is saved and reused on subsequent calls to the same site.

API credential flow (use_credential)

When an AI agent needs to make an authenticated API call on your behalf:

Agent: "Get my top 10 starred repos"
         ↓
use_credential("github.com", target_url="api.github.com/users/psam-717/starred")
         ↓
psamvault decrypts the API key locally, makes the HTTP request,
returns only the response — the credential is NEVER in the agent's context

Supports three injection modes:

• Bearer token — Authorization: Bearer ***
• API key header — <custom-header>: <key>
• Basic auth — Authorization: Basic base64(user:pass)

The fields parameter lets you return only the response keys you need, reducing token usage.

CLI command flow (run_with_credential)

When an agent needs to run a CLI tool that requires a credential (upload to PyPI, push to a private git repo, log into Docker, publish an npm package):

Agent: "Upload my package to PyPI"
         ↓
run_with_credential("pypi", "twine upload dist/*",
                    inject_as="env", env_var_name="TWINE_PASSWORD")
         ↓
psamvault decrypts the credential locally, spawns the subprocess
with the credential injected as an env var (or piped via stdin)
         ↓
All stdout and stderr is scanned for the credential value
and redacted before being returned
         ↓
Agent receives only the redacted output — the credential NEVER
appears in the agent's context

Supports two injection modes:

• env (default) — credential set as an environment variable (e.g. TWINE_PASSWORD, GITHUB_TOKEN, NPM_TOKEN). When TWINE_PASSWORD is used, TWINE_USERNAME=__token__ is set automatically.
• stdin — credential piped via stdin (e.g. for docker login).

Use cases include: twine upload, git push, docker login, npm publish, pip install (private repos), and any CLI tool that needs an API key or password.

Protecting your .env files (scan_and_protect)

Agent: "Protect the secrets in my project"
         ↓
scan_and_protect scans the project directory for .env files
         ↓
Detects API keys, passwords, tokens (pattern matching)
         ↓
Encrypts each secret into the psamvault vault
         ↓
Replaces plaintext with "psamvault:KEY_NAME" placeholders
         ↓
Your app resolves them at runtime with pv-dotenv

Secrets can be stored under a project namespace by passing project_name:

• Keys stored as project_name/.env/KEY_NAME for clean per-project organisation
• When omitted, keys are stored as env/.env/KEY_NAME (backwards-compatible)
• Use list_api_keys(project_name="myproject") to view only that project's keys

After protecting, pair with pv-dotenv — a drop-in replacement for python-dotenv that resolves psamvault: placeholders at runtime. No code changes needed beyond the import:

# Before:
from dotenv import load_dotenv

# After:
from pv_dotenv import load_dotenv

Prerequisites

• Python ≥ 3.11
• psamvault installed and logged in

pipx install psamvault
psamvault configure
psamvault login

• Playwright Chromium browser

playwright install chromium

Installation

Prefer pipx (isolated venv). Avoid pip install into system Python — on Windows this often leaves a broken shim on PATH that shadows the good install.

pipx install psamvault-mcp
psamvault-mcp --version   # safe smoke test (prints and exits)
psamvault-mcp --help      # same — usage text, then exit

After install — resolve the real binary

If where psamvault-mcp / which -a psamvault-mcp shows more than one path, configure your MCP client with the absolute path under your user local bin (pipx), not the system Python3xx\Scripts copy:

OS	Typical pipx path
Windows	%USERPROFILE%\.local\bin\psamvault-mcp.exe
Linux / macOS	~/.local/bin/psamvault-mcp

Hardened client config (recommended)

Always pass an absolute command and clear PYTHONPATH so other tools (e.g. Hermes) cannot contaminate imports:

{
  "mcpServers": {
    "psamvault": {
      "command": "C:\\Users\\YOU\\.local\\bin\\psamvault-mcp.exe",
      "args": [],
      "env": { "PYTHONPATH": "" }
    }
  }
}

Grok Build (~/.grok/config.toml):

[mcp_servers.psamvault]
command = "C:\\Users\\YOU\\.local\\bin\\psamvault-mcp.exe"
args = []
enabled = true
tool_timeout_sec = 300

[mcp_servers.psamvault.env]
PYTHONPATH = ""

Then restart the agent session (or refresh MCP). Config edits do not always reload tools mid-chat. Verify with get_version, then list_vault_sites.

Full agent playbook (corrupt pipx, PATH shadowing, session timeout, reload): docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md.

Transport modes

psamvault-mcp primarily uses stdio transport (the MCP standard for desktop agents). HTTP/SSE transport is also available as an option.

stdio (default — for Hermes, Goose, Claude Desktop, Cline, Grok Build)

psamvault-mcp

Starts the MCP server over stdin/stdout. This is the default mode and works with all major MCP desktop clients.

Note for agents: a bare psamvault-mcp invocation waits on stdin for the MCP protocol. That is not a hang — use --version / --help for smoke tests, and let the host spawn the process for real use.

HTTP/SSE (for custom clients, remote setups, or network-accessible deployments)

psamvault-mcp --http --port 8433

Starts an HTTP server with Server-Sent Events (SSE) transport.

Option	Default	Description
--http	off	Enable HTTP/SSE transport
--port	8433	HTTP server port
--host	127.0.0.1	HTTP server bind address

Goose setup

Option A — One-click deeplink

Click or paste this URL into your browser while Goose Desktop is running:

goose://extension?cmd=psamvault-mcp&timeout=300&id=psamvault&name=psamVault&description=Use%20stored%20credentials%20without%20exposing%20them%20to%20the%20agent

Goose will prompt you to confirm, then the extension is added instantly.

Option B — Goose Desktop UI

1. Open Goose Desktop.

2. Click the sidebar button (top-left) → Extensions.

3. Click Add custom extension.

4. Fill in the form:

   Field	Value
   Type	Standard IO
   ID	psamvault
   Name	psamVault
   Description	Use stored credentials without exposing them to the agent
   Command	psamvault-mcp
   Timeout	300

5. Click Add.

The extension appears in your Extensions list — toggle it on to activate it.

Option C — Config file (advanced)

Edit ~/.config/goose/config.yaml and add the following under extensions::

extensions:
  psamvault:
    name: psamVault
    cmd: psamvault-mcp
    args: []
    enabled: true
    type: stdio
    timeout: 300

Save the file and restart Goose (or reload the session).

Verifying the extension works

Once added, start a Goose session and try:

What credentials do I have stored in my vault?

Goose will call list_vault_sites via psamvault-mcp. If you see your stored sites, everything is working.

Hermes setup

Connect to psamvault-mcp via stdio transport (default). Add this block to ~/.hermes/config.yaml under mcp_servers:

mcp_servers:
  psamvault:
    command: psamvault-mcp
    enabled: true

If you need HTTP/SSE transport instead (e.g. for remote access), start the server with --http and point Hermes at the SSE endpoint:

mcp_servers:
  psamvault:
    url: "http://127.0.0.1:8433/sse"
    enabled: true

psamvault-mcp --http --port 8433

Restart or reload Hermes — the tools will be discovered automatically.

Claude Desktop setup

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "psamvault": {
      "command": "psamvault-mcp"
    }
  }
}

Restart Claude Desktop after saving.

Grok Build setup

1. Install with pipx (see Installation).
2. Add the server to ~/.grok/config.toml using the absolute pipx path (example above), or to ~/.mcp.json if you already use that file.
3. Restart Grok or open /mcps and refresh so tools load into the session.
4. Confirm: grok mcp doctor psamvault → handshake OK, tools discovered.
5. Ensure the vault CLI session is active: psamvault login.

Other MCP clients

Any MCP client supporting stdio transport can use psamvault-mcp. Prefer the absolute pipx path over a bare command name:

{
  "mcpServers": {
    "psamvault": {
      "command": "/home/YOU/.local/bin/psamvault-mcp",
      "env": { "PYTHONPATH": "" }
    }
  }
}

For HTTP/SSE support, point the client at http://127.0.0.1:8433/sse.

Troubleshooting

Symptom	Guide
MCP will not start / agent cannot connect	docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md
pydantic / pydantic_core import errors with Hermes	docs/troubleshooting/PYTHONPATH-CONFLICT.md
Index of all troubleshooting docs	docs/troubleshooting/README.md

Quick recovery for a broken Windows pipx install:

pipx uninstall psamvault-mcp
Remove-Item -Recurse -Force "$env:USERPROFILE\pipx\venvs\psamvault-mcp" -ErrorAction SilentlyContinue
pipx install psamvault-mcp
# Point MCP config at: $env:USERPROFILE\.local\bin\psamvault-mcp.exe

Configuration

psamvault-mcp reads its backend URL from ~/.psamvault/config.env, written automatically by psamvault configure.

Variable	Default	Description
PSAMVAULT_API_URL	https://psam-vault-backend.onrender.com	psamvault backend endpoint
PSAMVAULT_LOG_LEVEL	INFO	Log verbosity. Accepts any standard Python level: DEBUG, INFO, WARNING, ERROR. Logs go to stderr.

To point at a self-hosted backend, set the variable in ~/.psamvault/config.env:

PSAMVAULT_API_URL=https://your-backend.example.com

Available tools

Tools are grouped by purpose so AI agents can find the right tool faster:

🛠 Entry & Orientation

Always start here to discover what tool to use.

Tool	Description
search_vault_tools	Discovery tool — call this first to find the right tool for your task
get_version	Return the installed psamvault-mcp version

🔐 Site Authentication

End-to-end: discover, check, and log into websites.

Tool	Description
list_vault_sites	List stored site names with username hints (no passwords). Call before browser_login
check_credential_exists	Check if a credential exists for a site. Returns username hint
get_username_for_site	Get the username only (not password) for a site
browser_login	Open a real browser and log into a website — credentials filled silently, never shown to the agent

🔑 API Key Operations

All tools that deal with API keys — discover, use, inject, and protect.

Tool	Description
list_api_keys	List stored API key names with service hints and project grouping (never key values). Optional project_name filter
use_credential	Make authenticated HTTP requests using stored API keys or site passwords — only the HTTP response is returned
run_with_credential	Run a CLI command with a credential injected via env var or stdin — all output redacted of the secret
scan_and_protect	Scan a project for .env secrets, encrypt them into psamvault, replace with placeholders. Supports project_name for per-project namespacing
export_key_to_mcp_config	Export a vault API key into a client MCP config file (Hermes, Claude, etc.) — auto-verifies HTTP keys before write, with skip_verify / verify_url overrides
export_key_to_env_file	Export a vault API key into an agent .env as a variable (agent="hermes" → HERMES_HOME/.env, or explicit env_path) — updates in place, timestamped backup, auto-verifies HTTP keys
verify_api_key	Verify a stored API key is valid against its provider's API. Returns success, verification, provider, status, detail

Key verification is mandatory before an export write. HTTP keys are probed against the provider's read-only endpoint, and a failed probe blocks the write — skip_verify=true cannot override it (it covers only providers that cannot be probed at all, and the result then records verification: skipped). Invalid keys never reach a config or .env.

Changelog and unreleased tracking

Two files, one rule: nothing merged to main should have to be rediscovered at release time.

File	Holds	Who writes it
CHANGELOG.unreleased.md	merges that are on main but not yet on PyPI — the answer to "what is pending for the next release?"	whoever merges the change (usually via a follow-up PR)
CHANGELOG.md	released history, newest first	rolled over at release time from the unreleased file

At release time the unreleased entries are used twice: pasted into the GitHub release notes and prepended to CHANGELOG.md under the new version heading; the unreleased file is then reset to its header. scripts/docs-sync-check.py fails the release when CHANGELOG.md's newest section is not the release the contract calls newest, so a release that forgets the roll-over cannot ship quietly.

Version lockstep (MCP ↔ skill)

The server and its usage skill are a pinned pair, and the pairing ships inside the wheel as mcp_server/compatibility.json (each MCP release → the skill version that documents it, plus the expected tool fingerprint).

psamvault-mcp compat --check                     # exit 0 in sync, 1 drift (advisory: a newer published release never changes this)
psamvault-mcp compat --check --json              # machine-readable
psamvault-mcp compat --apply                     # install the target release and bring the skill up to date
psamvault-mcp compat --apply --latest            # ...or the newest release published on PyPI — the only way OUT of an install that is already behind
psamvault-mcp compat --apply --allow-breaking    # required when the target REMOVES a tool, or is newer than the installed contract
psamvault-mcp compat --sync-skill                # skill-only update: install the clone's newest skill, MCP untouched
psamvault-mcp compat --apply --from-git          # install the local repo (merged but not yet released)
psamvault-mcp compat --apply --from-git --pull   # ...after stashing local changes and pulling origin/main

psamvault-mcp selfcheck                          # installed vs what a NEW session actually serves (exit 1 on mismatch)
psamvault-mcp doctor                             # why an install looks broken: entry points, pipx records, processes holding the venv
psamvault-mcp doctor --fix                       # ...and repair it (run when no session is holding the venv)

--apply exit codes: 0 ok, 1 install failed, 2 refused (needs --allow-breaking), 3 the contract's release is not on PyPI yet (publish it, or use --from-git). --check only ever returns 0 or 1 — an available update is news, not breakage.

The check runs as a subcommand of the server's own entry point, so it needs no separate install and no venv path. On Windows the shim is psamvault-mcp.exe (the same one your MCP host config already calls); the pre-0.5.3 standalone compat console script was removed in 0.5.3 because pipx never linked it onto PATH — it answered command not found.

The recorded skill version is a floor, not a pin. Each release says the minimum skill version that documents it, and any skill at or above that floor is healthy:

State	Meaning
skill ≥ floor	✅ fine — the skill may legitimately move ahead of the MCP
skill < floor	drift — the skill is older than the server it documents; --sync-skill repairs it
skill missing	drift (same remedy)

That is what makes a skill-only update possible: improving the description of an existing tool is a skill change with no MCP release behind it. Edit the skill in the clone, then:

psamvault-mcp compat --sync-skill     # installs the clone's working-tree skill, if it meets the floor

--sync-skill reads the clone as-is (mirrors --from-git: uncommitted skill work is installable), snapshots the current skill first, and applies two guards so the skill can never move backwards silently:

Guard	Behaviour
floor	refuses when the clone's skill is below the floor the installed server requires — and writes nothing
no downgrade	refuses when the clone's skill is older than the skill already installed (a clone parked on an older branch holds an older skill); the message names the clone, its branch and both versions. --allow-downgrade overrides

--check also reports skill_source / skill_source_stale — when the clone is behind the installed skill it says so, because a silent downgrade opportunity is exactly what nobody notices.

A contract entry exists the moment a release is merged, before it ships. The index pre-check is deliberately advisory: PyPI's JSON API lags an upload (CDN cache), so it never blocks an install that would succeed — it only explains a real failure (exit 3). Use --from-git for the merged-but-unreleased case.

Upgrade safety (--apply)

Same model as the psamvault CLI's upgrade path: local work is never lost, and a failed upgrade is never left installed.

Step	What it does
Snapshot	copies the installed skill aside (backups/backup-<stamp>/, keeps the newest 5) before overwriting it
--pull	stashes uncommitted work (untracked included), git pull --ff-only origin main, then restores it. A failed pull restores immediately and stops; a conflicting restore leaves the work parked in a labelled stash and prints the recovery commands
Repo report	--from-git prints branch, HEAD, dirtiness and position vs origin/main (fetched, or marked "as of the last fetch"), and warns when the venv is an editable/source install that a released wheel would detach
Smoke test	imports the freshly installed server in a fresh interpreter from a neutral cwd — so the repo tree cannot masquerade as the install — and reports its version + tool count
Rollback	if the install fails or the smoke test fails, the previously installed release is put back automatically

• The installed server wins — the skill is pulled to match it, never the reverse, and never rolled back: an older clone skill is refused (see the guards above).
• A release marked breaking is never applied without --allow-breaking: a silently disappearing tool is exactly the change a human should see.
• get_version reports the pairing (compatibility.paired_skill_version, newest release, breaking_pending), so an agent can self-check without extra tooling.
• A tool count alone is not a version check: v0.5.0 removed one tool and added another, leaving the count at 13 — only the fingerprint reveals that.
• tests/test_compat.py fails when the newest contract entry disagrees with the code's actual tool surface, so a release that forgets to record itself cannot ship quietly.
• scripts/docs-sync-check.py is the release-time docs gate: it fails when any doc still names a tool the code dropped, claims a stale tool count, omits a tool, or disagrees with the contract. Run it first in every release — a tool count alone cannot reveal a renamed or removed tool.

Architecture

The MCP server manages a single Playwright Chromium instance in-process. No subprocess daemon is used — the browser lives in the same process as the MCP server. If the browser crashes, it is automatically restarted on the next browser_login call.

This eliminates the fragile 3-process chain (MCP → CLI daemon → browser) that caused connection errors with certain MCP clients (e.g. Goose's ECONNREFUSED on internal proxy ports).

Example agent prompts

Once connected, you can ask your agent things like:

• "What credentials do I have stored in my vault?"
• "What API keys do I have stored?"
• "Log me into kaggle.com"
• "Open github.com and log me in"
• "Check if I have a credential stored for z.ai"
• "Get my top 10 starred repos from GitHub"
• "Upload my package to PyPI"
• "Push to my private repo"
• "Protect the secrets in my project directory"

Related projects

Package	What It Does
pv-dotenv	Drop-in replacement for python-dotenv — resolves psamvault: placeholders at runtime
psamvault-cli	CLI + vault management — store, list, and manage credentials

Testing

# From the repo root
pytest

Tests live in tests/ and cover crypto primitives, session management, consent logic, the API client (with httpx mocking), and MCP tool behaviour. The test suite requires no real network access or OS keychain — all external dependencies are mocked.

Security

• Credentials are decrypted locally on your machine — never sent to the agent
• The agent only receives HTTP responses or redacted CLI output, never credential values
• All communication with the psamvault backend uses HTTPS
• The browser is managed in-process — no subprocess daemon or internal HTTP proxy
• CLI command output is scanned for the credential value and redacted before returning to the agent

License

MIT — see LICENSE.