@puffle/secret-valet

A tiny MCP server and CLI for giving an agent a password without the agent ever seeing it.

The model asks for a password. You type it into the terminal, masked. The agent gets back only an opaque handle like google/admin. Later the agent can ask the tool to use that handle — fill a form field, run a command with the secret in an environment variable, etc. — and the value is injected by the tool, never returned to the model.

Install

npm install -g @puffle/secret-valet
# Optional browser form filling:
npm install -g playwright
npx playwright install

Use as an MCP server

Add to your MCP client (Claude Code, Cursor, Codex, etc.):

{
  "mcpServers": {
    "secret-valet": {
      "command": ["npx", "-y", "@puffle/secret-valet", "mcp"]
    }
  }
}

The agent can call:

• prompt_for_secret(secret_id="google/admin") — you type the password at the terminal. If the agent has no terminal (e.g. Codex CLI), it falls back to a local web form at http://127.0.0.1:<port>/<token> and waits for you to submit.
• use_secret(secret_id="google/admin", action="fill_form", args={"url": "https://admin.google.com/...", "selector": "input[type=password]", "submit": true}) — the tool types it into the browser.

Use from the terminal

# store
secret-valet prompt google/admin
# run a command with the secret in $SECRET
secret-valet exec google/admin -- curl -u "user:$SECRET" https://example.com
# fill a form
secret-valet fill google/admin --url https://example.com/login --selector "input[type=password]" --submit

Security notes

• Passwords are stored in the OS keyring (macOS Keychain, Linux Secret Service / KWallet, Windows Credential Locker) via @napi-rs/keyring.
• The tool never writes the secret value back to the agent. The exec action only exposes the value as an environment variable to the child process.
• The fill_form action uses Playwright to type directly into the browser.
• No secret is ever printed in error messages.

Development

npm install
npm run build
npm test

License

MIT