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

Using the Plugin

Once installed or enabled in Codex, you can ask for tasks like:

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

The 1Password desktop app may prompt for approval when Codex connects to the MCP server or accesses an Environment.

Exposed MCP Tools

The plugin exposes these 1Password MCP tools to Codex:

• authenticate
• list_environments
• create_environment
• rename_environment
• list_variables
• append_variables
• create_local_env_file
• list_local_env_files

Releasing

Each release gets its own PR. Don't change the version number in feature PRs.

1. Create a release branch from the latest main, named after the new version, and push it:

   git checkout main
   git pull
   git checkout -b release/v0.3.0
   git push -u origin release/v0.3.0
   

   The Prepare release workflow commits a version bump in plugins/1password/.codex-plugin/plugin.json and an empty 0.3.0 section in CHANGELOG.md to the branch, then opens a Release v0.3.0 PR.

2. Wait for the Release v0.3.0 PR to appear (usually under a minute; you can watch the run in the Actions tab), then pull the workflow's commit:

   git pull
   

   If you pull before the workflow finishes, you won't get its commit, and your next push will be rejected.

3. Open CHANGELOG.md and write what changed under Features, Fixes, or Security. Delete any heading you don't use. The new section includes a comment listing the PRs merged since the last release, to help you remember what went in. Delete the comment when you're done.

4. Commit and push:

   git commit -am "Update changelog for v0.3.0"
   git push
   

5. Merge the PR.

6. Build the submission ZIP from the updated main (see Packaging for Submission) and upload it to the existing 1Password plugin at platform.openai.com/plugins with Upload plugin to make changes. After OpenAI approves it, open the approved version and select Publish plugin.

OpenAI doesn't read this repo, so merged changes reach the plugin directory only after a new ZIP is uploaded, reviewed, and published. Installs from GitHub use main directly.

Packaging for Submission

To build the ZIP for a Skills Only submission to the OpenAI plugin directory:

./scripts/package-skill-submission.sh

This writes dist/1password-skill-submission.zip and validates it before exiting. Upload that file in the submission portal.

A skills-only bundle may not declare mcpServers, .mcp.json, apps, .app.json, or interface.screenshots, but this repo keeps .mcp.json so the plugin still works as a local install. The script resolves that by staging a copy and stripping those pieces there, so your working tree is never modified.

Two structural rules cause most rejections, and the script handles both:

• The ZIP must contain exactly one plugin root, so .codex-plugin/plugin.json sits either at the ZIP root or inside its only top-level directory. Zipping the repo root fails (several top-level entries), and so does zipping a bare skill folder (no manifest).
• Do not use Finder's "Compress" to build the archive by hand; it adds __MACOSX entries.

To check an archive that was built some other way:

python3 scripts/validate_submission_zip.py dist/1password-skill-submission.zip

Note that a skills-only listing installs the skill but does not configure the MCP server, so users follow the Requirements section of SKILL.md to enable it themselves. Submitting the MCP server through the directory instead would require a production HTTPS server URL with domain verification, which does not apply to a local stdio server.

License

MIT. See LICENSE.