---
name: seren-passwords
description: "Manage a Seren Passwords end-to-end-encrypted vault through the Seren MCP server: list vaults, read/create/update/delete login, API-credential, and secure-note items, handle item transfer and attachments, and generate strong passwords - acting as a provisioned agent identity or, locally, with the user's master password."
---
# Seren Passwords

Use this skill when a user needs to read or manage entries in their Seren Passwords vault - looking up a login, storing an API credential, rotating a password, or keeping a secure note. Seren Passwords is end-to-end-encrypted: the password service only ever stores ciphertext and public keys. Decryption and encryption happen inside the MCP runtime using a delegated agent key; the password service never sees plaintext.

This skill drives the Seren MCP server's `passwords_*` tools. It does not require the `seren` CLI and does not implement vault crypto itself; hosted MCP uses the user's delegated Seren Passwords agent identity. The backend `/skill.md` route serves this Markdown document only; when installed from the [`seren/seren-passwords` skill package](https://github.com/serenorg/seren-skills/tree/main/seren/seren-passwords), companion files such as the optional Python bridge are available from the skill repository.

## Prerequisites: get the agent a key

An agent operates on a vault only after the vault owner has **provisioned** it and **granted** it access. This is a one-time setup the human runs from the seren CLI:

```bash
# Provision an agent identity and grant it access to a vault (or all vaults).
seren passwords agent provision --vault <vault-id|all> --access write   # or --access read
```

This generates the agent's keypair, registers the agent identity, re-seals the granted vault key(s) to the agent, mints a scoped API key, and writes everything to a `0600` key file under the user's config directory (`<config>/seren/passwords/agents/<identity-id>.json`). The seren MCP server loads that file at startup and authenticates as the agent automatically - no master password is ever involved on the agent path.

For hosted MCP (`https://mcp.serendb.com/mcp`), do not use the local agent key file path. Start a hosted consent request with `passwords_request_access`, send the returned `consent_url` to the user, and poll `passwords_grant_status` with the returned `request_id` after the user approves in the browser. Hosted MCP stores the delegated agent credential encrypted at rest and uses it only for the authenticated user's `passwords_*` tool calls. Do not send a master password or private key through a tool argument.

Hosted MCP can also return browser handoff URLs for actions that require the account signing key or whole-vault plaintext handling, such as creating a vault, rotating a vault key, granting membership, completing an invitation, importing, or exporting.

Related CLI commands the user may need:

```bash
seren passwords agent list                       # list provisioned agents and their granted vaults
seren passwords agent revoke <agent-id>          # revoke the whole agent identity
seren passwords agent revoke <agent-id> --vault <vault-id>   # revoke just one vault membership
```

If more than one agent key file is present, the MCP selects one via the `SEREN_PASSWORDS_AGENT_ID` environment variable.

## Auth modes

- **Agent-key mode (default, headless).** When an agent key file is present the MCP acts as that agent. Least privilege: the agent can only touch the vaults it was granted, and access is revocable server-side and immediately. This is the normal mode for skills and automation.
- **User mode (local only).** A human running the MCP locally can instead operate with full account authority by calling `passwords_unlock` once per session; the master password is read from the `SEREN_PASSWORDS_MASTER_PASSWORD` environment variable or a secure terminal prompt - never as a tool argument - and is held only in memory. This mode is rejected in hosted MCP deployments. Call `passwords_lock` when done; the session also expires after idle time.

## Interfaces

Use the best available interface for the runtime.

- Prefer the `seren passwords` CLI when running in a trusted local shell and the user has authorized command execution. It is the full-featured local interface and is usually best for provisioning/revoking agents, account or vault administration, import/export, rotation, troubleshooting, and workflows where the CLI can prompt locally for human credentials.
- Prefer MCP tools when the agent is running hosted/headless, cannot execute the CLI, already has `passwords_*` tools available, or needs to operate through a delegated agent identity inside an MCP session.
- For current flags and subcommands, run `seren passwords --help` and `seren passwords <subcommand> --help`.
- Never paste master passwords, private keys, recovery material, or revealed vault plaintext into chat. Let the CLI prompt locally, and reveal secrets through MCP only when the task actually requires it.

## Tools

All tools operate through the MCP server; you never construct HTTP requests or handle key material directly.

- `passwords_vaults_list` - list the vaults available to this agent/session (id, name, key version).
- `passwords_items_list` - list items (id and title only) in a vault. `vault_id` is optional when exactly one vault is available.
- `passwords_item_get` - fetch one item. **Decrypted content is redacted by default**; pass `reveal: true` only when the user actually needs the secret value. Without `reveal`, you get id, title, tags, and item kind.
- `passwords_item_create` - create an item. Set `kind` to `login`, `api_credential`, or `secure_note`, plus `title` and the fields for that kind (login: `username`/`password`/`urls`; api_credential: `key`/`credential_kind`; secure_note: `body`), with optional `tags` and `sensitive`.
- `passwords_item_update` - update an item by `item_id`. Only the fields you pass change; everything else is preserved.
- `passwords_item_delete` - move an item to trash. `passwords_item_restore` - restore a trashed item. `passwords_item_duplicate` - copy an item to another vault. `passwords_item_move` - move an item to another vault.
- `passwords_attachments_list`, `passwords_attachment_upload`, `passwords_attachment_download`, `passwords_attachment_delete` - manage item attachments. Upload/download uses base64 plaintext at the MCP boundary, so treat attachment content like any other revealed secret.
- `passwords_request_access` / `passwords_grant_status` - hosted MCP vault-access setup through a browser consent URL.
- `passwords_unlock` / `passwords_lock` - enter/leave user (master-password) mode; local modes only (see above).
- `passwords_generate_password` - generate a strong value locally (no vault access). `mode` is `random` (length + character classes), `passphrase` (`word_count`, `separator`, `capitalize_first`), or `hex` (length).
- Admin and account-signing workflows are available through additional `passwords_*` tools when the active mode has authority: vault create/update/archive/rotation/import/export, audit list/verify, agents list/freeze, memberships, invitations, approvals, and live shares. Prefer the exact MCP tool schema when using these less common operations.

## Typical workflows

**Look up a credential the user already stored:**
1. `passwords_vaults_list` (skip if the user named the vault).
2. `passwords_items_list` to find the item by title.
3. `passwords_item_get` with `reveal: true` to read the secret - then use it for the user's task; do not echo it into logs, summaries, or any untrusted output.

**Store a new login (generating a strong password):**
1. `passwords_generate_password` with `mode: random`.
2. `passwords_item_create` with `kind: login`, the `title`, `username`, the generated `password`, and any `urls`.

## Repository package helper

The [`seren/seren-passwords` skill package](https://github.com/serenorg/seren-skills/tree/main/seren/seren-passwords) includes `scripts/seren_passwords_bridge.py` for environments that can run Python but cannot call MCP tools directly. Prefer native MCP tools when they are available. The bridge reads one JSON request from stdin, opens a short-lived hosted MCP session, calls one `passwords_*` tool, prints the result as JSON, and exits.

Set `SEREN_API_KEY` to a bearer token accepted by the hosted MCP server. Set `SEREN_MCP_URL` when the endpoint is not `https://mcp.serendb.com/mcp`. The bridge reads connection settings only from the environment, not from request JSON.

Examples:

```bash
python scripts/seren_passwords_bridge.py <<'JSON'
{"action":"vaults_list"}
JSON
```

```bash
python scripts/seren_passwords_bridge.py <<'JSON'
{"action":"create_api_key","title":"Staging API","key":"secret-value","credential_kind":"api_key","tags":["staging"]}
JSON
```

Supported bridge actions: `vaults_list`, `items_list`, `item_get`, `item_create`, `item_update`, `item_delete`, `item_restore`, `item_duplicate`, `item_move`, `attachments_list`, `attachment_upload`, `attachment_download`, `attachment_delete`, `request_access`, `grant_status`, `generate_password`, `create_login`, `create_api_key`, and `create_note`. You can also call any MCP tool directly with `{"tool":"passwords_items_list","arguments":{"vault_id":"..."}}`.

## Security notes

- The server cannot read vault contents; never assume it can decrypt or "look up" a secret for you.
- An agent can only access vaults it was explicitly granted. If a tool returns a not-authorized error, the user must grant local access with `seren passwords agent provision` or hosted access with `passwords_request_access`.
- Treat retrieved secrets as sensitive: use them for the requested task only, and never write them to logs, files, commit messages, or responses the user did not ask for.
- Treat downloaded attachment bytes as revealed secrets. Decode `content_base64` only when the task requires the attachment content, and do not persist it unless the user explicitly asks.
- Revocation is immediate and server-side - `seren passwords agent revoke` cuts off the agent even if its key file still exists locally.