1password-mcp

1Password MCP

Security model

The official 1Password MCP server never returns secret values to the agent. It manages Environments, variable names, and .env mounts. Secrets stay in 1Password and are injected at runtime into authorized processes only.

Never:

• Ask the user to paste secret values into chat if 1Password can manage them
• Read a mounted .env file to verify it — use list_local_env_files instead
• Echo, log, or repeat secret values the user pastes — refer by variable name only

MCP-first workflow

When this plugin is installed, prefer the bundled 1password MCP tools over CLI for Environments work. The CLI skill is the fallback for vault items, op run, and operations MCP cannot do.

Prerequisites

Run ${CLAUDE_PLUGIN_ROOT}/scripts/status.sh if connection fails. Requires:

1. 1Password desktop app installed and unlocked
2. Settings → Labs → Enable local MCP server
3. Settings → Developer → Integrate with MCP clients

The user must approve each MCP action in the 1Password desktop app.

Tool reference

Tool	Purpose
authenticate	Get accountId — call first every turn unless you already have it
list_environments	List Developer Environments (names + IDs)
create_environment	Create a new Environment
rename_environment	Rename an Environment
list_variables	List variable names only (no values)
append_variables	Add or update variables (user provides values via 1Password UI)
create_local_env_file	Mount Environment as local .env (macOS/Linux)
list_local_env_files	List existing .env mounts for an Environment

Parameter naming: Responses may use account_id / environment_id; tool calls use camelCase: accountId, environmentId.

For detailed flows, see references/mcp-tools.md.

Standard flows

Authenticate and resolve Environment

1. Call authenticate → store accountId
2. Call list_environments with accountId
3. Pick the target Environment from context or ask the user — do not guess
4. Store environmentId

Mount this repo's .env

1. Authenticate and resolve Environment
2. list_local_env_files to check for existing mount
3. Derive absolute path: {workspace_root}/.env
4. create_local_env_file with accountId, environmentId, environmentName, mountPath
5. Report mount path — do not read the file

Add variables

1. Confirm names with user; collect values only if user explicitly wants to set them
2. Authenticate and resolve Environment
3. list_variables first to see existing names
4. append_variables — use concealed: true for secrets, false for URLs/flags

Create new Environment for a project

1. authenticate → create_environment with project name
2. Offer to mount .env and add common variable placeholders (API_KEY, DATABASE_URL, etc.)

When to escalate to CLI skill

• Reading vault items (op item get, secret references op://...)
• Wrapping MCP server configs with op run --environment
• Service account or CI/CD secret loading
• Shell plugin auth for third-party CLIs

Error handling

Failure	Action
MCP server unavailable	Direct user to enable Labs MCP + Developer integration; run /1password-setup
CLI not signed in	Run /1password-login — user runs op signin and approves in desktop app
Auth denied	User must unlock 1Password and approve the prompt; retry /1password-login
create_local_env_file fails	Confirm platform support; check absolute path
Tool schema differs	Use the schema exposed in the current MCP session exactly

Example prompts

• "List my 1Password Environments"
• "Create a local .env mount here"
• "Show variable names in my project environment"
• "Add a placeholder for my OpenAI API key"
• "Create a new Environment called my-project"