Provides tools for managing Proton Pass vaults, items (logins/notes), TOTP codes, secret references, password generation, and vault sharing via the official pass-cli binary.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@protonpass-mcp show me my login for github.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for Proton Pass. It wraps the official pass-cli binary and exposes 14 tools so any MCP-compatible AI assistant (Claude Desktop, Claude Code, etc.) can manage your vaults, credentials, and secrets.
Note: Proton Pass has no public REST API. This server uses the official
pass-clibinary under the hood. The CLI is currently in beta and requires a Visionary or higher Proton plan.
Related MCP server: Proton-MCP
Vault management — list, create, share vaults
Item management — list, view, create (login / note), update, trash, restore
TOTP — read live 2FA codes from stored items
Secret references — retrieve any field via pass://Vault/Item/field URIs
Password generation — generate cryptographically secure passwords
Account info — inspect the currently authenticated Proton account
Dockerized — no local Node.js or pass-cli installation required on the host
Persistent sessions — session tokens survive container restarts via a named Docker volume
Dependency | Version |
Docker | 24+ |
Proton Pass account | Visionary plan or higher (CLI beta requirement) |
No Node.js, npm, or pass-cli installation is needed on your host machine — everything runs inside the Docker image.
protonpass-mcp/
├── src/
│ └── index.ts # MCP server — tool definitions and handlers
├── Dockerfile # Multi-stage build (TypeScript → runtime + pass-cli)
├── docker-compose.yml # Optional: run via Compose
├── mcp-config.json # MCP client configuration snippet
├── .env.example # Environment variable template
├── package.json
└── tsconfig.jsondocker build -t protonpass-mcp .The build installs Node.js, downloads and installs pass-cli from Proton's official installer, compiles the TypeScript source, and produces a minimal runtime image.
The MCP server is non-interactive. Run this once to log in and save the session to the named Docker volume:
docker run --rm -it \
-e PROTON_PASS_KEY_PROVIDER=fs \
-v protonpass-session:/root/.local/share/proton-pass-cli \
--entrypoint pass-cli \
protonpass-mcp:latest login --interactiveEnter your Proton credentials (email, password, TOTP if enabled) when prompted. The session token and encryption key are written to the protonpass-session volume and reused automatically on every subsequent server start.
To verify the session is working:
docker run --rm \
-e PROTON_PASS_KEY_PROVIDER=fs \
-v protonpass-session:/root/.local/share/proton-pass-cli \
--entrypoint pass-cli \
protonpass-mcp:latest user infoWindows (cmd / PowerShell): Replace
\line continuations with^(cmd) or`(PowerShell), or write the command on a single line.
Tip: Re-run the login command if your session expires.
Copy the contents of mcp-config.json into your client's configuration file.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"protonpass": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "PROTON_PASS_KEY_PROVIDER=fs",
"-e", "PASS_LOG_LEVEL=warn",
"-v", "protonpass-session:/root/.local/share/proton-pass-cli",
"protonpass-mcp:latest"
]
}
}
}Claude Code (~/.claude/settings.json):
{
"mcpServers": {
"protonpass": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "PROTON_PASS_KEY_PROVIDER=fs",
"-e", "PASS_LOG_LEVEL=warn",
"-v", "protonpass-session:/root/.local/share/proton-pass-cli",
"protonpass-mcp:latest"
]
}
}
}After saving the config, restart your MCP client. The server starts automatically on demand — Docker launches a fresh container for every session and removes it when done (--rm).
If pass-cli and Node.js (v22+) are already installed on your machine:
npm install
npm run build
node dist/index.jsConfigure your MCP client to run node /path/to/protonpass-mcp/dist/index.js directly.
Tool | Description | Required params |
| List all accessible vaults | — |
| Create a new vault |
|
| List items (all vaults or filtered) | — |
| View full item details including credentials |
|
| Create a login credential item |
|
| Create a secure note item |
|
| Update fields of an existing item |
|
| Move an item to trash (soft delete) |
|
| Restore a trashed item |
|
| Get the current live TOTP code |
|
| Generate a secure random password | — |
| Read a field via |
|
| Show authenticated account details | — |
| Share a vault with another Proton user |
|
The view_secret tool accepts pass:// URIs identifying any field of any item:
pass://<vault-name>/<item-name>/<field>Built-in fields: username, password, email, url, note, totp.
Custom fields are addressed by their exact name (case-sensitive).
Examples:
pass://Work/GitHub/password
pass://Personal/Netflix/username
pass://Servers/Production DB/noteRole | Permissions |
| Read, write, share |
| Read, write |
| Read-only |
Variable | Default | Description |
|
| Key storage backend. Use |
| — | Encryption key when |
| platform default | Override session storage path. |
|
| Log verbosity: |
When using Docker Compose, copy .env.example to .env and edit the values — Compose picks it up automatically:
cp .env.example .envOtherwise, set them in docker-compose.yml or in the args array of your MCP client config.
Session volume: The protonpass-session Docker volume contains your Proton Pass session token and (when using PROTON_PASS_KEY_PROVIDER=fs) your encryption key. Treat it with the same care as a private key file. Back it up securely.
PROTON_PASS_ENCRYPTION_KEY: If you set this variable, do not store it in version-controlled files. Pass it via a secrets manager or a .env file excluded from git.
Command injection: The server uses execFile with argument arrays — no shell interpolation occurs. User-supplied strings are passed as discrete arguments, not interpolated into a shell command.
No secrets in tool output: view_item and view_secret return whatever pass-cli outputs. Ensure your MCP client does not log tool results to untrusted locations.
Container isolation: Each MCP session spawns an isolated container (--rm). The container has no network access beyond what Docker grants by default and no host filesystem access beyond the named session volume.
Error: pass-cli: command not found
The image was not built with the Proton installer. Rebuild with docker build --no-cache -t protonpass-mcp ..
Error: no session found / Error: not authenticated
Re-run the authentication command from step 2. The session may have expired.
Error: permission denied on volume
Ensure the protonpass-session volume was created by Docker and is accessible. Run docker volume inspect protonpass-session to verify.
pass-cli hangs on login inside the container
The --interactive flag is required for terminal-based login. Make sure it is present in the docker run command.
Items return IDs but you need names
Use list_vaults to get vault share IDs, then list_items with that vault_id to get item IDs. The view_secret tool accepts human-readable names via the pass:// URI syntax.
Create a new login credential item in a vault.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Website URL (optional) | |
| note | No | Secure note attached to this item (optional) | |
| title | Yes | Item title | |
| password | No | Password (optional) | |
| username | No | Username or email (optional) | |
| vault_id | Yes | Vault share ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the create action without disclosing behavioral details such as vault existence requirements, password generation behavior, or what happens after creation. No safety or side-effect information is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler words. It conveys the core purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema or annotations, and the description does not explain return values, side effects, or usage context relative to sibling tools. Given the complexity of 6 parameters and the create semantics, the description is insufficient for an agent to fully understand how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 6 parameters, so the description adds no additional parameter semantics. The term 'login credential' aligns with username/password fields, but this is redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new login credential item, specifying the resource type (login credential) and location (in a vault), which differentiates it from sibling create_note and create_vault tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives like create_note or update_item. There is no mention of prerequisites, exclusions, or recommended use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new secure note item in a vault.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | Note content | |
| title | Yes | Note title | |
| vault_id | Yes | Vault share ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose mutation effects, prerequisites, and return behavior. It only states 'create new', providing none of the additional behavioral context needed for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the tool's core purpose without redundant or extraneous words; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity and all params are documented, but with no output schema and no annotations, the description could have added expected return value or a pointer to list_vaults for obtaining vault_id. Overall adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and fields are self-descriptive ('Vault share ID', 'Note title', 'Note content'). The tool description itself adds no parameter-level detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new secure note item in a vault' uses a specific verb (create) and distinct resource (note item in vault), clearly distinguishing it from sibling tools like create_login and create_vault.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for creating note entries but provides no explicit guidance on when to choose it over alternatives such as create_login or update_item, nor any prerequisites like having an existing vault_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Proton Pass vault.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Vault name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states the action without any details on side effects, permissions, uniqueness constraints, or what happens upon successful creation. As a mutation tool, the lack of any behavioral context is a significant omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, with the action and resource front-loaded and no filler. It is efficient, though it may be too minimal to convey important context, but that is a completeness issue rather than conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should provide more context about the operation's behavior, potential errors, or usage prerequisites. The simple sentence covers only the basic purpose, leaving important gaps for a mutation tool, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the 'name' parameter as 'Vault name', and the description adds no additional parameter information. With 100% schema coverage, the baseline is 3, and the description does not enrich the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new Proton Pass vault'), providing a precise and unambiguous purpose. It inherently distinguishes from sibling tools like list_vaults or create_login by specifying the resource as a vault.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. The name implies it is for creating vaults, but there is no mention of prerequisites or situations where other tools (e.g., create_login, create_note) would be preferred. This is implied usage rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a cryptographically secure random password.
| Name | Required | Description | Default |
|---|---|---|---|
| length | No | Password length (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavior. It mentions 'cryptographically secure' and 'random', implying a safe, stateless operation, but does not disclose what the tool returns (e.g., a plaintext string), potential side effects, or any restrictions. This is minimal information for an agent to predict tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the essential function without extraneous detail. It is front-loaded with the action verb and fully readable at a glance, earning full marks for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, and the description sufficiently states its core function. However, it lacks an explanation of the return value (e.g., the generated password string) and any usage context relative to sibling tools. It is minimally viable but not richly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single 'length' parameter with a default value and type. Since schema description coverage is 100%, the description adds no additional meaning. The baseline score of 3 applies because the schema carries the semantic burden effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Generate') and resource ('password'), with a qualifier ('cryptographically secure') that distinguishes it from other password-related operations. Among sibling tools focused on vaults and items, this is the only password generation utility, so it is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or typical scenarios (e.g., generating a password for a login). It simply states the function, leaving the agent to infer appropriate usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current TOTP one-time code for an item that has 2FA configured.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Item ID | |
| vault_id | Yes | Vault share ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose that the code is 'current' and that the item must have 2FA configured, but it does not mention time-based expiration, read-only nature, or failure behavior when 2FA is not configured. Some context is provided, but more could be shared.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and immediately conveys the tool's purpose, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-defined parameters and no output schema. However, the description lacks details about return format, time-sensitivity, or error cases. It is adequate but not fully complete given the absence of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, both parameters have basic descriptions ('Item ID' and 'Vault share ID'). The description does not add meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clear resource ('current TOTP one-time code for an item that has 2FA configured'). It clearly distinguishes this tool from siblings like view_item, generate_password, or view_secret by specifying the exact purpose and precondition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when a TOTP code is needed for an item with 2FA, but it does not explicitly state when not to use it or how it compares to alternatives. There are no exclusions or alternative tool names mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about the currently authenticated Proton account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It explicitly states 'Get information,' indicating a read-only operation, and adds the important context that it applies to the 'currently authenticated' account, implying authentication requirements. No side effects are mentioned, but for a read operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description clearly states the purpose, it does not specify what information is returned (e.g., email, user ID). Since there is no output schema, this lack of detail is a gap. However, the tool's simplicity mitigates the impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. The description adds no parameter details, but with no parameters, the baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and specifies the resource as 'information about the currently authenticated Proton account,' clearly distinguishing it from sibling tools like list_vaults or create_login.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for retrieving information about the authenticated Proton account. No explicit alternatives are mentioned, but the scope of 'currently authenticated account' provides adequate context for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List items stored in a vault. Omit vault_id to list items across all vaults.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_id | No | Vault share ID (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description carries the full burden but only discloses the scope behavior (omit vault_id). It doesn't mention return format, ordering, or potential large result sets, but the read-only nature is implied by 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description sufficiently communicates its function and the key optional behavior. However, it doesn't clarify what types of items are returned or any pagination, but these are not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers vault_id 100% with 'Vault share ID (optional)', but the description adds meaning by explicitly stating the effect of omitting it (lists across all vaults). This clarifies user intent beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('items'), and clearly defines the scope via optional vault_id. It distinguishes from sibling list_vaults by focusing on items rather than vaults.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that omitting vault_id lists across all vaults, implying when to use the optional parameter. However, it doesn't explicitly mention alternatives or when not to use this tool (e.g., for viewing a single item's details).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Proton Pass vaults accessible to the current account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden for behavioral disclosure. It indicates a read operation but does not state the return format, potential pagination, permission implications, or any side effects. Minimal disclosure beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that immediately conveys the purpose. No wasted words or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters, but there is no output schema or behavioral detail. The agent learns that it lists vaults but not the structure of the result or any filtering or sorting behavior. Adequate for a trivial operation, yet leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. No parameter documentation is needed, and the description does not add parameter details. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List all Proton Pass vaults accessible to the current account' – a specific verb ('List'), resource ('vaults'), and scope ('accessible to current account'). This distinguishes it from siblings like create_vault (creation) and list_items (items within vaults).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage as a read-only listing operation, but no explicit when-to-use or alternatives are provided. The description itself is the only guidance, giving a clear action but no context about when to prefer this over related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a trashed item.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Item ID | |
| vault_id | Yes | Vault share ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states 'Restore a trashed item', but does not disclose side effects, permission requirements, behavior when the item is not trashed, or the response shape. This is a mutation tool with minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is appropriately sized for the action described, though it lacks depth that would affect other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is too minimal to provide complete context. It does not explain what 'restore' means operationally, the required state of the item, or any side effects. This is a significant gap for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are documented in the schema with simple descriptions ('Item ID' and 'Vault share ID'), achieving 100% coverage. The tool description adds no additional meaning about how the parameters relate or any constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'restore' and resource 'trashed item', clearly distinguishing it from sibling tools like trash_item and view_item. It conveys the core action without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives, such as update_item or view_item. It does not mention that the item must be in the trash or that this is the inverse of trash_item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an item to trash (soft delete). Use restore_item to undo.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Item ID | |
| vault_id | Yes | Vault share ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the key behavior: 'soft delete' (reversible) and mentions the undo path via restore_item. It does not detail side effects like item visibility or permissions, but the core behavioral trait is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences that front-load the action and include a useful cross-reference. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description provides the essential behavior (soft delete) and the undo path. It could add what happens to the item after trashing, but this is not needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters ('Item ID', 'Vault share ID'). The description itself adds no extra parameter information, which is fine given the schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move an item to trash') and the resource ('item'), and specifies 'soft delete' to distinguish it from permanent deletion. This differentiates it from sibling tools like update_item or view_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly points to restore_item for undoing the action, which clarifies the primary alternative scenario. However, it does not discuss when to use trash_item versus other modification tools, though the operation is fairly self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing item. Only the fields you supply will change.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | New URL (optional) | |
| note | No | New note (optional) | |
| title | No | New title (optional) | |
| item_id | Yes | Item ID | |
| password | No | New password (optional) | |
| username | No | New username (optional) | |
| vault_id | Yes | Vault share ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It discloses the key behavioral trait that only supplied fields change, but it does not cover permissions, reversibility, response format, or error semantics, which are relevant for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action and resource. Every word adds value, and there is no filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no annotations, and no output schema, the description is adequate for basic invocation but lacks information about return values, error cases, or specific conditions for use. It captures the essential partial-update behavior but leaves some operational context undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters and their optionality. The description's partial-update statement adds general context but does not provide additional per-parameter meaning, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Update an existing item') and clearly distinguishes from sibling operations like create_login, trash_item, and restore_item. The second sentence adds partial-update semantics, making the tool's purpose explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing item, but it does not explicitly state when to choose this tool over alternatives such as create_login or restore_item. There is no mention of exclusions or prerequisites, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View the full details of an item (title, username, password, URLs, notes, custom fields, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Item ID | |
| vault_id | Yes | Vault share ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('view') and the content returned, but does not mention that the output may contain sensitive data (passwords), nor does it explicitly confirm a read-only nature, permissions, or error behavior. This is a notable gap for a tool that exposes secrets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the key verb and resource, then lists examples of the content. Every word contributes to clarity with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (two parameters) and the absence of an output schema, the description adequately explains what the tool returns by listing the full field types. It could be more complete by noting that the output contains sensitive data or that the item must belong to the specified vault, but it is sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters ('Item ID' and 'Vault share ID'), achieving 100% coverage. The tool description adds no extra parameter-level detail beyond what the schema states, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('View') and resource ('item'), and enumerates the full details returned (title, username, password, URLs, notes, custom fields). This distinguishes it from sibling tools like list_items, which likely provide a summary, and view_secret, which handles a different resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., list_items for summaries, view_secret for secrets). Usage is only implied by the tool's name and purpose, with no mention of exclusions or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific field value from an item using a pass:// URI. URI format: pass://// Fields: username, password, email, url, note, totp, or custom field name. Example: pass://Work/GitHub/password
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Secret reference URI (e.g. pass://Work/GitHub/password) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the read-only nature ('Retrieve') and URI format, but does not mention whether the secret is returned in plaintext, any security implications, or error handling for missing fields. This is adequate for a simple read but lacks deeper behavioral context, especially for a secret-sensitive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: first sentence states the action, then the URI format, field list, and example. Every sentence adds necessary information with no filler. It is appropriately sized for a single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is nearly complete for a simple retrieval tool: explains URI construction and valid fields. The only gaps are the lack of error-handling details and a potential ambiguity with the sibling get_totp tool, since totp is listed as a field here. This could confuse an agent about which tool to use for TOTP, so it's not a perfect 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning beyond the schema: it defines the URI structure (pass://<vault-name>/<item-name>/<field>), enumerates valid field names (username, password, email, url, note, totp, custom), and provides a concrete example. This gives the agent complete guidance for constructing the uri parameter, far exceeding the schema's generic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Retrieve a specific field value from an item using a pass:// URI.' It specifies the resource (item field) and distinguishes from siblings like view_item (whole item) and get_totp (TOTP-focused). The verb 'retrieve' is specific and the URI format clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's use case is clear: when you need a single field value, identified by a pass:// URI. It implies this is the tool for targeted retrieval, but it does not explicitly state alternatives or exclusions (e.g., 'for full item use view_item'). Thus it falls short of explicit when-not guidance but still provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_logincreate_notecreate_vaultgenerate_passwordget_totpget_user_infolist_itemslist_vaultsrestore_itemshare_vaulttrash_itemupdate_itemview_itemview_secretScored across 14 tools
Each tool targets a specific resource and action, with only minor overlap between get_totp and view_secret (which can retrieve the totp field via URI). For example, list_items vs view_item are clearly distinct in scope (metadata vs full details).
All tools follow a consistent verb_noun snake_case pattern (e.g., list_vaults, create_note, trash_item, generate_password). There is no mixing of camelCase, vague verbs, or irregular naming conventions.
14 tools is well-scoped for a password manager, covering vaults, items, lifecycle, sharing, TOTP, and password generation. Each tool has a distinct place and the set feels intentional rather than bloated.
The tool surface covers core CRUD/lifecycle for vaults and items, plus sharing, TOTP retrieval, and password generation. Minor gaps exist, such as no permanent delete (only trash/restore) and limited item creation types (only login and note), but these are workable.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
