1Password Codex Plugin

What is 1Password Codex Plugin about?

The plugin connects Codex to the 1Password desktop app's local MCP server, providing AI‑driven access to Developer Environments while keeping secret values under 1Password control.

How to use 1Password Codex Plugin?

Install the 1Password desktop app on macOS, Windows, or Linux and enable Integrate with MCP clients under Settings → Developer.
Install or enable the plugin within Codex (via the marketplace entry .agents/plugins/marketplace.json).
Ask Codex natural‑language commands such as:
- “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”
Approve any prompts from the 1Password app when Codex attempts to access the MCP server.

Key features of 1Password Codex Plugin

Secure secret handling – secret values never leave 1Password; Codex only receives metadata.
Environment management – list, create, rename environments via MCP tools.
Variable operations – list, append, and create local .env files.
Cross‑platform support – works on macOS, Windows, and Linux.
Packaging scripts – scripts/package-skill-submission.sh builds a compliant ZIP for OpenAI’s plugin directory; validation script ensures correct structure.

Use cases of 1Password Codex Plugin

Automating local development setup by having Codex generate .env files from stored secrets.
Rapidly inspecting available environment variables without exposing actual secret values.
Adding placeholder variables for new services (e.g., API keys) during prototyping.
Enhancing team onboarding by letting AI guide developers through secure environment configuration.

FAQ from the 1Password Codex Plugin

Q: Do secret values ever get sent to Codex? A: No. The plugin only exposes variable names and metadata; actual secret values remain locked in the 1Password vault.

Q: Which operating systems are supported? A: macOS, Windows, and Linux.

Q: What if the “Integrate with MCP clients” setting is disabled? A: Ask an administrator to enable it under Policies → Sharing and permissions → Agentic permissions → Local MCP server.

Q: Can I submit this plugin to the OpenAI marketplace? A: Yes. Use the provided packaging script to create a “Skills Only” ZIP; the script strips MCP‑specific files to meet marketplace requirements.

Q: Is any additional server setup required? A: No. The 1password-mcp binary is installed with the desktop app and runs automatically when Codex invokes the MCP tools.

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.

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

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.

1Password Codex Plugin