1Password Codex Plugin

This repository contains a Codex plugin that connects Codex to the 1Password desktop app’s local MCP server for 1Password Developer Environments.

The plugin lets Codex help with secure project environment setup, such as listing Developer Environments, inspecting variable names, adding variables, and creating local .env mounts. Secret values remain controlled by 1Password and are never shared with Codex.

Note: This plugin supports macOS, Windows, and Linux.

Documentation

https://www.1password.dev/environments/mcp-codex-server

What’s Included

• plugins/1password/.codex-plugin/plugin.json - Codex plugin metadata and UI configuration.
• plugins/1password/.mcp.json - MCP server configuration for the 1Password desktop app’s bundled 1password-mcp binary.
• plugins/1password/skills/1password-environments/SKILL.md - Codex skill instructions for using 1Password Developer Environments.
• plugins/1password/skills/1password-environments/agents/openai.yaml - Skill interface settings (display name, icons, brand color). These belong here rather than in SKILL.md frontmatter, which only carries the skill’s name, description, and other Agent Skills spec fields.
• plugins/1password/assets/ - Plugin icon and logo assets.
• .agents/plugins/marketplace.json - Local marketplace entry that points Codex at plugins/1password.
• scripts/package-skill-submission.sh - Builds the ZIP for a “Skills Only” submission to the OpenAI plugin directory.
• scripts/validate_submission_zip.py - Checks a built ZIP against OpenAI’s submission rules.
• .github/workflows/prepare-release.yml - Bumps the version, adds a changelog section, and opens a release PR when a release/vX.Y.Z branch is pushed.
• CHANGELOG.md - Release notes for each version.

Prerequisites

• macOS, Windows, or Linux with the 1Password desktop app installed.
• Integrate with MCP clients turned on under Settings > Developer in the desktop app.
• Access to a 1Password account with Developer Environments enabled.

If Integrate with MCP clients is disabled by an administrator, ask your administrator to check Policies > Sharing and permissions > Agentic permissions > Local MCP server.

The MCP server runs via the 1password-mcp alias, which the 1Password desktop app installs on your PATH:

1password-mcp

macOS 27 Golden Gate

On macOS 27 Golden Gate, macOS blocks apps from accessing 1Password app data by default and doesn’t ask for permission. Until you allow it, the MCP server can’t start.

1. Open System Settings > Privacy & Security > Files & Folders.
2. Select the app you run Codex in: the Codex app, your terminal (like Terminal, iTerm, or Ghostty), or your editor (like Visual Studio Code).
3. Turn on the setting that starts with “Data shared by 1Password”. The rest of the name depends on which 1Password apps you’ve installed.