The mcp-1password server provides read-only, opaque-by-default access to 1Password vaults, items, secrets, and environments, with strong emphasis on secret redaction and explicit consent for sensitive operations.
Core (Always Available) Tools:
sdk_capabilities — Describe the server's capability surface and preferred no-plaintext paths.
op_session_status — View 1Password CLI session state and active capability gates.
vault_list — List all visible vaults.
vault_get / vault_permissions_get — Get vault details and accessor permissions.
group_get — Get group details, optionally including vault permissions.
item_search — Search items by title, tags, or category.
item_get_metadata — Get item metadata with all field values redacted.
environment_get_variables / environment_get_variable — List or get 1Password Environment variables, values redacted.
password_generate / password_generate_memorable — Generate random passwords or passphrases in plaintext (requires a reason and explicit acknowledgement: I_UNDERSTAND_THIS_RETURNS_GENERATED_SECRET_PLAINTEXT).
Disabled by Default (Require Opt-in & Explicit Acknowledgement):
secret_reveal / environment_reveal_variable — Reveal plaintext secrets; requires --enable-secret-reveal=true and per-call acknowledgement (I_UNDERSTAND_THIS_RETURNS_SECRET_PLAINTEXT).
Write/update/delete operations on items or vaults — requires --enable-writes=true / --enable-destructive-actions=true.
Vault permission mutations — requires --enable-permission-mutation=true.
Script execution with injected secrets — requires --enable-script-runner=true.
Unrestricted shell commands — requires --enable-unrestricted-runner=true.
Security & Audit:
All sensitive actions are automatically logged to a JSONL audit file.
Secrets are opaque by default; plaintext is never returned unless explicitly enabled and acknowledged.
Supports desktop, service-account, and connect authentication modes, and operates over stdio (default) or http (bearer token protected).
Provides integration with 1Password for managing vaults and items (create, read, update, archive, delete) with opaque-by-default secret handling, plus a script runner that injects 1Password CLI authentication for pre-approved or unrestricted shell commands.
Click on "Install 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., "@mcp-1password list my vaults in 1Password"
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.
Status: Public Beta
This package is under active development (v0.x). The API and CLI flags may change between minor versions. The underlying
@1password/sdkdependency is also a beta release. Pin an exact version (mcp-1password@x.y.z) in production-like environments.
A Model Context Protocol server that exposes 1Password to AI agents with opaque-by-default secret handling. Secrets are never revealed unless you explicitly opt in.
Read and search vaults, items, and environments with secrets redacted by default.
Create tracked item requests, then update, archive, and delete items and vaults when write/destructive capabilities are enabled.
Manage group permissions on vaults when permission mutation is enabled.
Reveal plaintext secrets only on explicit request with a per-call acknowledgement.
Generate plaintext passwords only with a reason and explicit acknowledgement.
Run pre-approved scripts with injected 1Password-backed environment values.
Optionally run unrestricted local shell commands under explicitly approved workspace roots, after local browser confirmation.
Use stdio by default, or a local/single-user HTTP transport protected by a bearer token.
Write a JSONL audit log for sensitive actions at ~/.onepassword-mcp/audit.jsonl.
Related MCP server: Agentic Vault
Node.js >= 20.10
1Password desktop app for --auth-mode=desktop; this requires the 1Password beta channel with SDK integration enabled.
1Password Connect for --auth-mode=connect; the POC only accepts a localhost Connect host.
1Password CLI (op) only when scripts need CLI authentication or you configure script runner CLI auth; Connect-backed envSecretRefs do not require op.
Desktop auth requires the 1Password beta channel and SDK integration:
In 1Password, switch to the beta channel: Settings -> Updates -> Beta channel.
Enable SDK integration: Settings -> Developer -> Connect with 1Password SDKs.
# Public beta install
npm install -g mcp-1password@beta
# Connect-only binary after global install
OP_CONNECT_TOKEN="<connect-token>" \
mcp-1password-connect --connect-host=http://127.0.0.1:8090
# Run on demand without a global install
npx -y mcp-1password@beta --auth-mode=desktop --account="My Account"During beta, prefer mcp-1password@beta or an exact version instead of relying on the default npm tag.
Use mcp-1password-connect when you want a path where Connect is the only possible 1Password backend. This binary forces --auth-mode=connect, rejects Desktop/service-account auth, rejects non-Connect op CLI auth modes, and never instantiates the Desktop SDK service.
# From the project root, create/update the trust file and manifest first.
mcp-1password-connect trust-workspace
OP_CONNECT_TOKEN="<connect-token>" \
mcp-1password-connect \
--connect-host=http://127.0.0.1:8090 \
--enable-script-runner=true \
--script-runner-allowlist-manifest="$HOME/.onepassword-mcp/workspace-trust.json"For each new project that should be trusted for Connect workspace commands:
mcp-1password-connect trust-workspaceThen call workspace_trust_reload in the running MCP session.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"1password": {
"command": "npx",
"args": [
"-y", "mcp-1password@beta",
"--auth-mode=desktop",
"--account=1Password account name or UUID"
]
}
}
}{
"mcpServers": {
"1password": {
"command": "npx",
"args": ["-y", "mcp-1password@beta", "--auth-mode=service-account"],
"env": {
"OP_SERVICE_ACCOUNT_TOKEN": "<service-account-token>"
}
}
}
}Run the local Connect containers from docker-compose.connect.example.yml, then start the MCP without Desktop auth:
OP_CONNECT_TOKEN="<connect-token>" \
mcp-1password \
--auth-mode=connect \
--connect-host=http://127.0.0.1:8090Connect mode supports vault/item reads, tracked placeholder creation through item_request_create, managed-item review through item_request_list, item update/delete, password_update, password_read, and secret_reveal. It does not expose generic password_create or item_create, vault mutation, group permissions, 1Password Environments, files, or item archive. See docs/connect-local-poc.md.
OP_MCP_HTTP_BEARER_TOKEN="$(openssl rand -base64 32)" \
mcp-1password \
--auth-mode=desktop \
--account="My Account" \
--transport=httpHTTP security: The HTTP transport is designed for local/single-user use. The bearer token must be at least 16 characters, and
--http-require-bearer=falseis only allowed on localhost. If you bind the server to any interface other than127.0.0.1, put it behind a reverse proxy with TLS termination (nginx, Caddy, Traefik). For multi-user or public deployments, add a real upstream authorization layer such as OIDC/OAuth with client identity, scopes, and expiry.
Every flag can also be set through an environment variable.
Flag | Environment variable | Default | Description |
|
|
|
|
|
| - | Account name or UUID, required in desktop mode |
|
| - | Token, required in service-account mode |
|
|
| Localhost Connect API URL, required to stay on localhost for this POC |
|
| - | Connect access token, required in connect mode |
|
|
| Connect request timeout |
|
|
| Allow plaintext secret reveal |
|
|
| Allow tracked item requests plus item/vault updates and vault creation |
|
|
| Allow archive and delete operations |
|
|
| Allow vault permission changes |
|
|
| Allow execution of allowlisted scripts |
|
|
| Enable |
|
| - | Absolute path to an allowlist file; repeatable |
|
| - | Absolute path to a manifest listing allowlist files; repeatable |
|
| - | Trusted workspace root; repeatable |
|
|
| Allow the separate free-form shell command runner |
|
| - | Root path eligible for unrestricted execution approval; repeatable |
|
|
| Require local approval page before commands can run |
|
|
| Local approval server bind host; localhost only |
|
|
| Local approval server port; |
|
|
| In-memory approval lifetime |
|
|
| Free-form command timeout |
|
|
| Encrypted local approval grants file for the approval page's 24h remember checkbox |
|
|
| Local 32-byte AES key file used to encrypt remembered approval grants |
|
|
| Lifetime for approvals remembered across MCP sessions |
|
| - | Required only when disabling session approval; exact value: |
|
|
| Path to the |
|
|
|
|
|
|
|
|
|
|
| HTTP bind address |
|
|
| HTTP port |
|
|
| HTTP path prefix |
|
|
| Require |
- |
| - | Bearer token required by default with |
|
| Localhost origins for the current port | Browser origins allowed for HTTP transport; strict |
|
|
| Maximum active HTTP MCP sessions |
|
|
| Idle HTTP session expiry |
|
|
| HTTP request timeout |
|
|
| Audit log path |
|
|
|
|
The script runner lets agents invoke pre-approved shell commands with 1Password-backed environment injection. In --auth-mode=connect, the MCP exposes workspace_trust_list, workspace_command_run, and workspace_trust_reload; envSecretRefs are resolved through Connect and injected directly into the child process without the op binary, OP_SESSION, or Desktop SDK auth. With Desktop or service-account auth, the MCP exposes the older op_script_list, op_script_run, and op_script_reload_allowlists tools, and the runner can also inject CLI authentication for commands that call op. By default, only startup-configured commandId entries can run. In Connect mode, workspace_trust_list resolves the requested workspaceRoot against startup-configured workspace trust entries and returns workspaceCommandResolution; when that resolution reports freeformCommands: true, workspace_command_run may accept a free-form command rooted in that workspace or its subdirectories. The startup command catalog and workspace trust files can be reloaded on demand with the reload tool.
For a new Connect-mode project, run this from the project root:
mcp-1password trust-workspaceThis creates or updates .onepassword-mcp.json in the project, enables workspace commands for that project, and adds the file to ~/.onepassword-mcp/workspace-trust.json. Start the MCP with that manifest configured once:
mcp-1password \
--auth-mode=connect \
--enable-script-runner=true \
--script-runner-allowlist-manifest="$HOME/.onepassword-mcp/workspace-trust.json"If the MCP is already running with that manifest, call workspace_trust_reload after trusting a new project.
For local single-user sessions where preapproving every command is too expensive, start the server with:
mcp-1password \
--auth-mode=desktop \
--account="My Account" \
--enable-unrestricted-script-runner=true \
--op-cli-path=/absolute/path/to/opWith --enable-unrestricted-script-runner=true, op_script_run ignores --script-runner-root, --script-runner-allowlist, and --script-runner-allowlist-manifest. The first free-form op_script_run call returns an approvalUrl; open it locally, tick the checkbox, and type:
I_UNDERSTAND_THIS_ALLOWS_UNRESTRICTED_LOCAL_COMMAND_EXECUTIONBy default, that approval is in memory only and applies once per MCP server process. If you tick Remember this approval for 24 hours on this machine, the server writes an encrypted local grant containing only the approval scope and expiration timestamp. After approval, op_script_run accepts command instead of commandId, runs it through a non-login /bin/sh -c shell in the requested workspace, and still supports envSecretRefs so secrets are injected into the child process without being returned to the model. When the remembered grant expires, the approval page is required again.
Create a .onepassword-mcp.json file at the root of your project:
{
"version": 1,
"workspaceRoot": ".",
"allowWorkspaceCommands": false,
"commands": {
"deploy-staging": {
"description": "Deploy to staging",
"command": "/usr/local/bin/deploy.sh",
"args": ["--env", "staging"],
"cwd": ".",
"timeoutMs": 120000,
"sensitiveOutput": false
}
}
}command must be an absolute path to an executable.
The directory containing command is not automatically prepended to PATH. Use absolute paths in scripts, or configure --op-cli-path so the directory containing op can be injected.
In --auth-mode=connect, allowWorkspaceCommands: true marks the matching workspaceRoot, workspaceRoots, or workspaceRootPrefixes as a trusted workspace command scope. workspace_trust_list exposes the decision as workspaceCommandResolution.freeformCommands; when it is true, workspace_command_run accepts a free-form command for that resolved workspace or its subdirectories. Secrets passed with envSecretRefs are resolved through Connect only, injected only into the child process, and are not returned to the model. This is an explicit trust decision for local worktrees you control.
sensitiveOutput: true withholds stdout/stderr from the agent unless returnOutput=true is explicitly requested with reveal acknowledgement.
workspace_command_run in Connect mode and op_script_run in Desktop/service-account mode accept an optional envSecretRefs object that maps environment variable names to op:// references. The server resolves those references, injects only the values into the child process environment, and never returns or audits the plaintext values.
returnOutput=true does not require startup secret reveal for ordinary output. When envSecretRefs is provided or the command has sensitiveOutput: true, stdout/stderr/error messages are returned only with acknowledgePlaintext: "I_UNDERSTAND_THIS_RETURNS_SECRET_PLAINTEXT"; without that acknowledgement, execution is skipped with executionSkipped: true and outputState: "skipped_ack_missing". Returned stdout/stderr/error messages are redacted by exact secret value.
After editing a startup-configured command catalog or workspace trust file, call workspace_trust_reload in Connect mode or op_script_reload_allowlists in Desktop/service-account mode with a reason. If the edited file is invalid, the reload fails and the previous in-memory configuration remains active.
Use --script-runner-allowlist-manifest=/absolute/path/to/workspace-trust.json when you want to add or remove workspace trust or command catalog files without restarting the MCP process. Manifest entries may be absolute paths or paths relative to the manifest file:
{
"version": 1,
"allowlists": [
"/absolute/path/to/project-a/.onepassword-mcp.json",
"../project-b/.onepassword-mcp.json"
]
}After editing the manifest, call workspace_trust_reload in Connect mode or op_script_reload_allowlists in Desktop/service-account mode with a reason. Any new workspace roots are still checked against startup-configured --script-runner-root values when roots are provided.
When an agent needs a secret only to run a local command, it should not call password_read with reveal=true or secret_reveal first. Prefer this flow:
In Connect mode, call workspace_trust_list for the current workspace; in Desktop/service-account mode, call op_script_list.
In Connect mode, inspect workspaceCommandResolution: if freeformCommands=true, call workspace_command_run with command; otherwise pick a listed commandId that performs the operation.
Call workspace_command_run in Connect mode or op_script_run in Desktop/service-account mode with envSecretRefs, mapping environment variable names to op:// references.
Leave returnOutput=false unless command output is required.
This keeps the plaintext secret out of the model transcript while still letting the command receive it.
When an agent needs a new credential to exist in 1Password, prefer item_request_create over asking the user to paste the value. The tool creates a managed item with:
credential fields initialized to the __FILL_ME__ placeholder;
provenance fields for project, justification, and optional Linear ticket details;
managed tags such as mcp-managed, awaiting-fill, and project:<slug>;
op:// references that the agent can wire into configs or scripts.
The user fills the returned references in 1Password. Later, item_request_list reports which managed items are still awaiting fill, without returning the credential values.
The unrestricted runner is a separate, dangerous escape hatch for trusted local worktrees where allowlisting every command is too expensive. Enable it only for roots you are willing to approve for arbitrary command execution:
mcp-1password \
--auth-mode=desktop \
--account="My Account" \
--enable-unrestricted-runner=true \
--unrestricted-runner-root=/absolute/path/to/trusted/worktreeWhen an MCP client first calls op_unrestricted_run for a configured root, the tool returns authorizationRequired: true and a local approvalUrl. Open that URL on the same machine, tick the risk checkbox, and type:
I_UNDERSTAND_THIS_ALLOWS_UNRESTRICTED_LOCAL_COMMAND_EXECUTIONThat approval is in memory only and expires after --unrestricted-runner-approval-ttl-ms. It is not written to config. The configured root is an approval scope, not an operating-system sandbox: approved commands run with your normal OS permissions and can still cd, read, write, or execute outside that path if the OS allows it.
op_unrestricted_run starts the command in the requested workspace root through /bin/sh -c on Unix-like systems, with a minimal inherited environment and no 1Password secret injection. The shell is intentionally non-login so local profile hooks such as RVM do not run before the requested command. Use op_script_run when a command needs 1Password values injected safely. As with script output, returnOutput=true without acknowledgePlaintext: "I_UNDERSTAND_THIS_RETURNS_SECRET_PLAINTEXT" skips execution and returns the required acknowledgement.
You can disable the browser approval page only with an explicit startup acknowledgement:
mcp-1password \
--auth-mode=desktop \
--account="My Account" \
--enable-unrestricted-runner=true \
--unrestricted-runner-root=/absolute/path/to/trusted/worktree \
--unrestricted-runner-require-session-approval=false \
--acknowledge-unrestricted-runner=I_UNDERSTAND_THIS_ALLOWS_UNRESTRICTED_LOCAL_COMMAND_EXECUTIONSecrets are opaque by default. Item fields are returned with valueState: "redacted" unless --enable-secret-reveal=true is passed.
Plaintext reveal requires explicit consent. Tools that return secrets require acknowledgePlaintext: "I_UNDERSTAND_THIS_RETURNS_SECRET_PLAINTEXT".
Password generators return a new plaintext secret. They require reason and acknowledgePlaintext: "I_UNDERSTAND_THIS_RETURNS_GENERATED_SECRET_PLAINTEXT", and audit the action without logging the secret.
Destructive actions and permission mutations require per-call acknowledgement. Use acknowledgeDestructive: "I_UNDERSTAND_THIS_CAN_DELETE_1PASSWORD_DATA" for archive/delete operations and acknowledgePermissionMutation: "I_UNDERSTAND_THIS_CAN_CHANGE_1PASSWORD_PERMISSIONS" for permissions.
Dangerous capabilities are opt-in and disabled by default, including writes, destructive actions, permission mutation, secret reveal, the script runner, the unrestricted script runner, and the unrestricted runner.
Every sensitive action is audited to a JSONL file. Secret references and auth tokens are automatically redacted from logs.
The default script runner uses spawn with shell: false, so shell injection is not available for commandId entries. Connect-mode workspace command resolution is intentionally broader: when workspaceCommandResolution.freeformCommands=true, the requested command runs through a non-login shell scoped by the resolved trusted workspace.
The unrestricted script runner is session-approved and intentionally broad. When enabled, op_script_run ignores startup command catalogs and workspace trust files, then runs free-form shell commands after a local browser approval once per MCP process. Use it only for single-user local sessions you already trust.
Remembered approvals are local, encrypted, and expiry-bound. The approval page can remember a grant for 24 hours by writing an AES-256-GCM encrypted file under ~/.onepassword-mcp; the file contains approval scope names and expiration timestamps, not 1Password secrets.
Configuration reloads are bounded and audited. workspace_trust_reload in Connect mode and op_script_reload_allowlists in Desktop/service-account mode only reload direct startup configuration paths and manifest trust anchors configured at startup, record the reload reason, and keep the previous in-memory configuration if validation fails.
Script secret injection is run-only. envSecretRefs values are resolved in memory, injected into the child process, redacted from returned output, and audited only by env var name, reference scheme, and reference hash.
Unrestricted runner approval is local and in-memory. op_unrestricted_run requires a configured root plus browser approval by default. Audit entries store command hashes and lengths rather than the raw free-form command.
Unrestricted runner roots are not a sandbox. The root limits which worktrees can request approval; it does not prevent an approved command from touching other paths allowed by the operating system.
Bearer token comparison uses crypto.timingSafeEqual to reduce timing attack risk.
HTTP binds to localhost (127.0.0.1) by default. It validates the Origin header, caps active sessions, expires idle sessions, and returns generic messages for server errors.
Resources and capabilities avoid sensitive local metadata. Local paths, 1Password account names, HTTP host/port, and the op binary path are not exposed to MCP clients.
errorMessage for scripts with sensitiveOutput: true is withheld unless output is explicitly requested with plaintext acknowledgement.
Resource URIs use the onepassword:// scheme instead of 1password://. Node.js URL parsing rejects schemes that start with a number, which breaks resource reads in practice.
npm run lint # TypeScript type checking
npm test # Test suite
npm run build # Compile to dist/Commits must follow Conventional Commits. This project uses release-please to automate CHANGELOG generation and version bumps.
The publish.yml workflow uses npm Trusted Publishing through OIDC. It does not use a long-lived npm token (NPM_TOKEN, NODE_AUTH_TOKEN, or a 1Password secret) for publication.
npm-side prerequisites:
package mcp-1password exists on npm and is associated with kefapps/onepassword-mcp-codex
a GitHub Actions trusted publisher is configured for repository kefapps/onepassword-mcp-codex
workflow filename: publish.yml
The GitHub workflow uses Node.js 24 and has the id-token: write permission required by npm to exchange the job OIDC identity for a short-lived publishing token. npm automatically generates provenance attestations when the package and GitHub repository are public.
See CHANGELOG.md.
Issues and pull requests are welcome. See CONTRIBUTING.md before opening a pull request.
Please report vulnerabilities privately instead of opening a public issue. See SECURITY.md.
MIT
Get one 1Password Environment variable by exact name, with the value redacted. When a secret is needed only by a command or local script, prefer op_script_run with envSecretRefs so the secret is injected into the child process and never returned in plaintext.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| environmentId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It mentions value redaction, but lacks details on error handling, permissions, or behavior for missing variables.
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 concise sentences with no fluff: first states purpose, second provides usage guidance.
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 low complexity and self-explanatory parameters, the description covers purpose and a key behavioral trait (redaction), though missing error case details.
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 0%, and the description does not explain the parameters environmentId or name, relying on self-explanatory names but adding no additional context.
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 gets one environment variable by exact name with value redacted, distinguishing it from siblings like environment_get_variables and environment_reveal_variable.
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 explicit guidance on when to prefer an alternative (op_script_run for secrets in scripts), but does not differentiate when to use this tool versus the sibling environment_get_variables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get 1Password Environment variables with values redacted. Supports simple client-side filtering by variable name. When a secret is needed only by a command or local script, prefer op_script_run with envSecretRefs so the secret is injected into the child process and never returned in plaintext.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| environmentId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that values are redacted and filtering is client-side. However, it does not mention authorization requirements, rate limits, or behavior for invalid environment IDs or empty results.
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 sentences, zero wasted words. Front-loaded with purpose and filtering capability, followed by a clear usage alternative. Ideal 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 description is mostly adequate for a simple list tool, covering purpose, redaction behavior, and an alternative use case. However, it lacks explanation of the 'environmentId' and 'limit' parameters, and does not describe the output format, which would be helpful given no 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 0%. The description only explains that 'query' supports filtering by variable name. It does not clarify the 'environmentId' or 'limit' parameters, leaving the agent to infer their purpose from the schema names alone.
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 retrieves environment variables with redacted values and supports client-side filtering by name. This distinguishes it from siblings like environment_get_variable (single variable) and environment_reveal_variable (reveals values).
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 explicitly advises against using this tool when a secret is needed by a command or script, recommending op_script_run with envSecretRefs instead. However, it does not differentiate when to use this tool versus its direct siblings like environment_get_variable or environment_reveal_variable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plaintext reveal is disabled in this server; this tool will fail until the server is restarted with OP_MCP_ENABLE_SECRET_REVEAL=true or --enable-secret-reveal=true. If the secret only needs to be consumed by a command or local script, do not call this tool. op_script_run is not available because the script runner is also disabled here; restart the server with --enable-script-runner=true plus startup --script-runner-allowlist or --script-runner-allowlist-manifest entries to allow no-plaintext secret consumption by scripts.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| reason | Yes | ||
| environmentId | Yes | ||
| acknowledgePlaintext | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses that the tool will fail unless the server is restarted with specific flags, and that it returns secret plaintext (implied by the warning about not calling it for other purposes). It also explains the required acknowledgment parameter.
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 paragraph that is somewhat repetitive. It front-loads the failure condition but could be more concise by separating the core purpose from the prerequisites.
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 tool has 4 required parameters and no output schema or annotations, the description is severely incomplete. It does not state the purpose, explain parameters, or describe the return value, leaving the agent with insufficient information to use the tool 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 has 4 required parameters with 0% description coverage. The description provides no explanation of what environmentId, name, reason, or acknowledgePlaintext represent or how to use them.
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 never states what the tool does. It only discusses its failure condition and provides workarounds. The name suggests 'reveal variable' but the description omits the core purpose.
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 advises not to call this tool if the secret can be consumed by a command/script, and suggests an alternative (op_script_run) with setup instructions. However, it does not clearly state when it is appropriate to use this tool (e.g., when plaintext reveal is enabled).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one group by ID. This is the only group read endpoint exposed by the official JS SDK beta today.
| Name | Required | Description | Default |
|---|---|---|---|
| groupId | Yes | ||
| includeVaultPermissions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must convey behavioral traits. It labels itself as a 'read endpoint,' implying no side effects, but does not disclose authentication requirements, rate limits, or potential errors. Minimal transparency beyond the 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?
Two sentences, each earning its place: the first defines the function, the second adds valuable context (uniqueness in the SDK). 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?
The description covers the tool's core purpose but lacks details on return values, error handling, and the meaning of the boolean parameter. For a simple get-by-ID tool, more is needed given no output schema and no parameter descriptions.
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 0%. The description does not explain the 'groupId' (format or meaning) or 'includeVaultPermissions' (purpose). The sole parameter information comes from the schema, which is unhelpful without descriptions.
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 'Get one group by ID', combining a specific verb with the resource. The second sentence distinguishes it as the only group read endpoint in the JS SDK beta, setting it apart from sibling 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?
The description implies usage when a group ID is known, but provides no guidance on when to use alternatives or when not to use this tool. Since it's the only group read endpoint, the context is straightforward, but no explicit when-to-use or when-not-to-use is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get item metadata with every field value redacted. Use secret_reveal only when plaintext is explicitly required.
| Name | Required | Description | Default |
|---|---|---|---|
| itemId | Yes | ||
| vaultId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the critical behavioral trait that all field values are redacted. With no annotations, this is essential. Could mention if it's read-only or requires specific auth, but the redaction note is key.
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 sentences, zero filler. Purpose and guidance packed efficiently. Front-loaded with core function.
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 no output schema and simple parameters, description covers redaction and alternative tool, but lacks detail on what metadata is returned (e.g., field names, structure, or error handling). Adequate but not thorough.
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 coverage is 0% and description does not explain vaultId or itemId (e.g., format, origin, or typical usage). Parameter names are suggestive but not semantically enriched.
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 'Get item metadata' with the crucial qualifier 'with every field value redacted,' distinguishing it from secret_reveal which returns plaintext. No 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?
Explicitly tells when to avoid this tool and use secret_reveal instead ('only when plaintext is explicitly required'), providing direct alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review placeholder items created with item_request_create and tagged 'mcp-managed'. Returns provenance plus filled/awaiting-fill status without returning credential values.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 50. | |
| project | No | Only return items whose provenance project matches this value. | |
| vaultId | No | Restrict to a single vault id. Omit to scan every visible vault. | |
| onlyAwaitingFill | No | When true, return only items the user has not filled yet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states the tool returns provenance and fill status and does not return credential values. The read-only nature is implied by 'review' and 'list' but not explicitly stated, and no side effects are mentioned. Still, it provides good insight into the tool's 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, well-structured sentence that front-loads the core purpose and key details. Every part is informative and there is no extraneous text.
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 description explains what the tool returns (provenance and fill status) and its filtering (tag-based), but it does not cover pagination, ordering, or default behavior for the limit parameter. Given the absence of an output schema, more detail about the return structure would improve completeness.
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 has 100% description coverage, with each parameter already described in the schema. The tool-level description does not add additional parameter-level semantics beyond what the schema provides, so it meets the baseline without exceeding it.
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 reviews placeholder items created by item_request_create with a specific tag 'mcp-managed'. It distinguishes itself by specifying what it returns (provenance and fill status) and explicitly what it does not return (credential values), making its purpose unique among sibling 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?
The description explains that the tool is for reviewing items created by item_request_create and tagged 'mcp-managed', providing clear context for when to use it. It does not explicitly mention alternatives or when not to use it, but the specificity of the tool's purpose and the mention of credential exclusion guide appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search item overviews by title/tags/category. If no vault is provided, the server searches every visible vault client-side.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| vaultId | No | ||
| includeArchived | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It reveals one behavioral trait (client-side fallback when no vault), but omits critical details like read-only status, permission requirements, rate limits, or side effects. For a search operation, this is insufficient.
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 very concise with two sentences, the first covering the core purpose. However, it sacrifices necessary detail, which limits its effectiveness despite the efficient structure.
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?
Missing output schema, no parameter explanations, and sparse behavioral context. For a tool with four parameters (including a limit), the description fails to cover pagination, return format, error modes, or the semantics of includeArchived. The agent would lack sufficient information to use the tool 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?
Schema description coverage is 0%, and the description does not explain any of the four parameters (query, vaultId, includeArchived, limit). The mention of 'title/tags/category' hints at the query's role but is too vague to guide correct usage.
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 ('Search') and resource ('item overviews') and specifies search criteria (title/tags/category). This distinguishes it from items that retrieve a single item or vault-level operations.
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 only mentions a behavioral detail about vault selection ('If no vault is provided, the server searches every visible vault client-side'), but offers no guidance on when to use this tool versus alternatives like password_read or item_get_metadata. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show non-secret 1Password CLI session state and runtime capability gates held by this MCP process.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool shows 'non-secret' information, indicating safety. However, it does not explicitly state side effects, authentication requirements, or whether it is read-only. With no annotations, the description could be more thorough.
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 sentence of 12 words, front-loaded with the verb and resource. No unnecessary words; every part contributes to understanding.
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 description is adequate for a simple read tool, but it does not explain the return format or how to interpret 'runtime capability gates'. With no output schema, more detail on expected output would improve completeness.
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?
There are zero parameters, so baseline is 4. The description adds context about the tool's purpose beyond the empty schema, confirming it shows session state and capabilities.
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 verb 'show' and the resource 'non-secret 1Password CLI session state and runtime capability gates', distinguishing it from sibling tools that deal with environment variables, items, passwords, and 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?
The description implies the tool is for checking session state and capabilities, which is unique among siblings. However, it does not explicitly state when to use it versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a strong random password and return it in plaintext for immediate use. Requires a reason and generated-secret acknowledgement.
| Name | Required | Description | Default |
|---|---|---|---|
| length | No | ||
| reason | Yes | ||
| symbols | No | ||
| includeDigits | No | ||
| excludeSimilar | No | ||
| includeSymbols | No | ||
| includeLowercase | No | ||
| includeUppercase | No | ||
| acknowledgePlaintext | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses a critical behavioral trait: the password is returned in plaintext, which is important for security. It also mentions the need for acknowledgement, but does not cover other behaviors like whether passwords are stored or other side effects.
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 sentences with no extraneous information. The key purpose and requirements are stated upfront, achieving maximal 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 tool's complexity (9 parameters, security-sensitive, no output schema), the description is too brief. It does not explain the return format beyond 'plaintext', lacks details on parameter effects, and provides no information about error cases or storage behavior.
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 schema has 0% description coverage for parameters. The description only mentions 'reason' and 'acknowledgePlaintext' but fails to explain the other 7 parameters (e.g., length, character sets), leaving their semantics unclear.
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 generates a strong random password and returns it in plaintext, which distinguishes it from sibling tools like 'password_generate_memorable' (memorable passwords) and 'password_read' (reading existing passwords).
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 mentions 'for immediate use' and that a reason and acknowledgement are required, but it does not explicitly state when not to use this tool or provide alternatives (e.g., using 'password_read' for existing passwords).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a memorable passphrase-like password and return it in plaintext for immediate use. Requires a reason and generated-secret acknowledgement.
| Name | Required | Description | Default |
|---|---|---|---|
| words | No | ||
| reason | Yes | ||
| separator | No | ||
| capitalize | No | ||
| includeNumber | No | ||
| acknowledgePlaintext | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the password is returned in plaintext and requires a reason and acknowledgment, which are important safety traits. However, it does not mention whether the password is stored or logged, or any post-generation behavior. With no annotations provided, the description bears full responsibility but only partially fulfills it.
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 extremely concise (22 words) and front-loads the core purpose in the first clause. The second clause efficiently lists requirements. Every sentence adds value, and there is no 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?
Given the tool has 6 parameters, no output schema, and no annotations, the description is insufficient. It omits details about optional parameters, return format, and side effects. The tool's moderate complexity demands more contextual information 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 description only references the required parameters 'reason' and 'acknowledgePlaintext' indirectly. The optional parameters (words, separator, capitalize, includeNumber) are not explained, despite the input schema providing no descriptions. This leaves the agent with incomplete understanding of how to configure the output.
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 generates a 'memorable passphrase-like password' and returns it in plaintext, distinguishing it from a generic password generator. The verb 'generate' and resource 'password' are specific, and the adjective 'memorable passphrase-like' clarifies the nature of the output.
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 explicit guidance is provided on when to use this tool versus alternatives like 'password_generate'. The description mentions requirements but does not explain context, exclusions, or preferred scenarios. Usage is only implied by the tool name and basic description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one password field or secret reference. Returns redacted metadata by default. Plaintext reveal is disabled in this server; reveal=true will fail. If the secret only needs to be consumed by a command or local script, do not request reveal. op_script_run is not available because the script runner is also disabled here; restart the server with --enable-script-runner=true plus startup --script-runner-allowlist or --script-runner-allowlist-manifest entries to allow no-plaintext secret consumption by scripts.
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | ||
| itemId | No | ||
| reason | No | ||
| reveal | No | ||
| vaultId | No | ||
| secretReference | No | ||
| acknowledgePlaintext | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses key behaviors: returns redacted metadata by default, plaintext reveal will fail, and script runner is disabled. It also provides context about server configuration for enabling script usage. However, it does not detail error conditions or side effects like logging.
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 front-loaded with the purpose but becomes verbose, especially with the script runner configuration details, which could be condensed. It is structured but includes non-essential operational guidance that could be separated.
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 no output schema and 7 parameters (0 required), the description covers core behavior and limitations but lacks details on return values (beyond 'redacted metadata'), error handling, and parameter relationships (e.g., field vs. secretReference). It is adequate but leaves gaps for a complete understanding.
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 0%, so the description must compensate. It mentions 'field', 'secretReference', and 'reveal' but provides no explanation for other required parameters like 'itemId', 'vaultId', 'reason', and 'acknowledgePlaintext'. The description adds minimal meaning beyond parameter names, leaving the agent underinformed.
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 begins with a clear verb and resource: 'Read one password field or secret reference.' It distinguishes from sibling tools by explicitly stating that plaintext reveal is disabled and that secret_reveal is not for this, and by noting that op_script_run is not available, which differentiates from script-based consumption.
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 explicit guidance on when to use (for reading metadata without plaintext), when not to use (do not request reveal if secret is for local script), and mentions an alternative (script runner configuration) and a limitation (script runner disabled). This fully informs agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe the capability surface exposed by this server, including the preferred no-plaintext path for consuming secrets in scripts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately indicates a read-only informational operation, but with no annotations, it does not disclose additional behavioral traits such as idempotency or side effects. For a simple informational tool, this is adequate.
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 wasted words. It is front-loaded with the main purpose and includes a specific important 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?
For a tool with no parameters, no output schema, and no annotations, the description is complete. It tells the agent exactly what the tool does without requiring additional context.
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 schema has zero parameters, so the description carries the full burden. It adds value by explaining the tool's purpose beyond the empty schema, meeting the baseline for no-parameter tools.
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 purpose: to describe the server's capability surface and the preferred no-plaintext path for secret consumption. This distinguishes it from action-oriented siblings like secret_reveal or password_generate.
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 when an agent needs to know available capabilities or secure secret consumption practices, but it does not explicitly state when to use this tool versus alternatives or provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plaintext reveal is disabled in this server; this tool will fail until the server is restarted with OP_MCP_ENABLE_SECRET_REVEAL=true or --enable-secret-reveal=true. If the secret only needs to be consumed by a command or local script, do not call this tool. op_script_run is not available because the script runner is also disabled here; restart the server with --enable-script-runner=true plus startup --script-runner-allowlist or --script-runner-allowlist-manifest entries to allow no-plaintext secret consumption by scripts.
| Name | Required | Description | Default |
|---|---|---|---|
| itemId | No | ||
| reason | Yes | ||
| fieldId | No | ||
| vaultId | No | ||
| reference | No | ||
| acknowledgePlaintext | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions the tool will fail if not enabled but does not disclose what happens on success, required permissions, or return format. 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 relatively short (three sentences) and avoids unnecessary text, but it is not front-loaded with core purpose and lacks clear structure.
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 sensitive tool with 6 parameters, no output schema, and no annotations, the description is severely incomplete. It fails to explain the tool's basic function, parameter usage, or return value, focusing solely on server configuration.
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 0%, and the description adds no information about any of the 6 parameters (itemId, reason, fieldId, vaultId, reference, acknowledgePlaintext). The const value for acknowledgePlaintext is not explained.
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 does not explicitly state that this tool reveals a secret in plaintext. It focuses on server configuration and failure conditions, making the purpose vague and only implied by the name.
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 negative guidance (when not to use and alternatives like restarting the server) but lacks positive guidance on when to use this tool versus siblings like environment_reveal_variable or password_read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get vault details and, optionally, accessor permissions for one vault.
| Name | Required | Description | Default |
|---|---|---|---|
| vaultId | Yes | ||
| includeAccessors | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'Get', implying a read operation, but does not disclose any behavioral traits like authentication needs, what happens if vaultId is invalid, or what 'accessor permissions' entails. Minimal transparency.
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 is front-loaded with the key action and resource. No extraneous 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?
Given the tool has no output schema, two parameters, and no annotations, the description is too minimal. It does not explain what 'vault details' includes or what the return format is. More context is needed for an agent to use 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?
Schema description coverage is 0%, and the description adds no meaning beyond the parameter names. It does not explain the format of vaultId or the default value for includeAccessors. No additional semantics provided.
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 verb 'Get', the resource 'vault details', and the optional inclusion of 'accessor permissions'. It distinguishes from sibling tools like vault_list (lists vaults) and vault_permissions_get (gets permissions) by specifying it retrieves details for one 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?
No guidance is provided on when to use this tool versus alternatives such as vault_list or vault_permissions_get. There is no mention of prerequisites, context, or when not 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 vaults visible to the authenticated 1Password integration.
| Name | Required | Description | Default |
|---|---|---|---|
| decryptDetails | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavior. It states listing vaults visible to the authenticated integration, implying read-only, but fails to mention whether results are paginated, any limits, or the effect of the decryptDetails parameter on output.
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, but it omits critical information about the parameter, making it too terse for effective use.
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 one parameter, no output schema, and no annotations, the description should explain decryptDetails and the expected output format. It fails to do so, leaving significant 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 coverage is 0% and the description does not mention the sole parameter decryptDetails, leaving its meaning entirely undefined. The description adds no value beyond the bare 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 'List vaults visible to the authenticated 1Password integration,' which is a specific verb-resource combination that distinguishes from siblings like vault_get (single vault) and vault_permissions_get (permissions).
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 versus alternatives, such as vault_get for detailed single-vault info or vault_permissions_get for authorization details. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get vault accessor permissions. The JS SDK beta exposes this through vault accessors.
| Name | Required | Description | Default |
|---|---|---|---|
| vaultId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Get vault accessor permissions', implying read-only behavior but omits any details about side effects, authentication requirements, rate limits, or error states. This is insufficient for a tool with zero annotation support.
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 sentences, no fluff. The second sentence provides optional context about the JS SDK beta, which, while not critical, adds useful information without being excessive.
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 simplicity (1 parameter, no output schema), the description is minimal. It lacks details about return format, error conditions, or prerequisites, which are important for an AI agent to use the tool correctly. The absence of such context makes 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 only parameter 'vaultId' has no description in schema (0% coverage). The description does not clarify its purpose, expected format, or how to obtain it, leaving the agent without essential guidance for correct invocation.
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 states 'Get vault accessor permissions' which clearly identifies the action (get) and resource (vault accessor permissions). It distinguishes from sibling tools like vault_get (vault details) and vault_list (list vaults) by specifying 'accessor permissions', though it assumes knowledge of the accessor concept.
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 on when to use this tool versus alternatives like vault_get or item_get_metadata. The mention of 'JS SDK beta' hints at a specific context but does not provide explicit when/when-not criteria or exclude scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but the multiple 'reveal' tools (environment_reveal_variable, secret_reveal, password_read with reveal) could cause confusion. Overall, agents can differentiate based on context.
Naming is mostly snake_case with verb_noun, but prefixes are inconsistent: some tools use domain prefixes (environment_, password_, vault_) while others lack them (secret_reveal, group_get). This mix reduces predictability.
15 tools is a reasonable count for a password manager server covering environment variables, items, passwords, vaults, groups, and session status. Slightly on the higher side but well-scoped.
The server covers read and generate operations well, but lacks write operations (create, update, delete) for items, vaults, and groups. This limits full lifecycle coverage for a password manager.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
An MCP server that integrates with Discord to provide AI-powered features.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
MCP server teaching AI agents to implement TideCloak: auth, E2EE, IGA, security analysis
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kefapps/onepassword-mcp-codex'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
