Use plugins and MCP servers in Codex

Codex uses the same plugins as ChatGPT. A plugin can add skills (reusable instructions) and MCP servers (tools that reach GitHub, Linear, your browser and so on) to a Codex session. You can also connect MCP servers directly, without a plugin.

This guide covers both, in the Codex CLI and in Codex inside the ChatGPT desktop app.

Before you start#

Install Codex and sign in:

npm install -g @openai/codex
# or: brew install --cask codex
codex

Choose Sign in with ChatGPT on first run. API-key sign-in also works, with limits described below.

Where things work:

All three share one MCP configuration file, ~/.codex/config.toml, so a server you add in one shows up in the others.

Plugin or MCP server?#

Install a plugin when one exists for the service: it bundles the MCP server with skills that tell Codex how to use it, and prompts you to connect the account when needed. Add a bare MCP server (step 7) when there's no plugin, when you're testing your own server, or when you want only the tools without the bundled instructions. You can use both at once.

1. Browse and install with /plugins#

Start Codex and open the plugin browser:

codex
/plugins

The browser groups plugins by marketplace, with one tab per source. OpenAI's built-in marketplace is shown as Codex official (its internal name is openai-curated). From here you can:

• Open a plugin to read what it contains.
• Install or uninstall it.
• Press Space on an installed plugin to turn it on or off.

Start a new session after installing. Bundled skills and tools only load when a session starts. If the plugin includes an MCP server that needs a login, you'll be asked to authenticate before its tools work.

2. Install from the command line#

The same actions are available as subcommands, which is handy in setup scripts:

# list installed plugins (add --json for machine-readable output)
codex plugin list
codex plugin list --marketplace openai-curated

# include plugins you haven't installed yet (requires --json)
codex plugin list --available --json

# install: PLUGIN@MARKETPLACE, or PLUGIN with --marketplace
codex plugin add linear@openai-curated
codex plugin add linear --marketplace openai-curated

# uninstall and remove the cached copy
codex plugin remove linear@openai-curated

Installed copies live under ~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/.

3. Add more marketplaces#

A marketplace is a JSON catalog of plugins, usually in a Git repository. Add one with:

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

Manage them with:

codex plugin marketplace list
codex plugin marketplace upgrade            # refresh all
codex plugin marketplace upgrade <name>     # refresh one
codex plugin marketplace remove <name>

Codex reads marketplace files from .agents/plugins/marketplace.json and, for compatibility, .claude-plugin/marketplace.json. That's why some community catalogs built for other agents also work. For example, Trail of Bits documents:

codex plugin marketplace add trailofbits/skills
codex plugin add <plugin-name>@trailofbits

You can also keep a repo marketplace at $REPO_ROOT/.agents/plugins/marketplace.json or a personal one at ~/.agents/plugins/marketplace.json. The format is covered in Publish a ChatGPT plugin.

4. Use a plugin in a session#

Once installed and enabled, you can:

• Describe the task. "Look at the failing CI run on my open PR and propose a fix." Codex picks matching skills and tools.
• Call a bundled skill by name. Type $ and choose the skill, or run /skills to browse.
• Check MCP tools. Run /mcp to list the active MCP servers, including those a plugin brought in.

When a plugin's tools run in Codex, your sandbox and approval settings still apply. Connections to outside services use that service's own login and permissions.

5. Enable a plugin for one project#

Plugins from a local or repo marketplace can be switched on or off per project. In the repository's .codex/config.toml:

[plugins."my-plugin@local-repo"]
enabled = true

The key is plugin-name@marketplace-name. Set enabled = false to turn it off for that project without uninstalling it.

Codex only loads .codex/config.toml for trusted projects. Project settings override user and system defaults, unless an admin enforces a value. Plugins your workspace admin imported through Admin > Plugins follow workspace policy instead.

6. Tune a plugin's MCP servers#

You can adjust MCP servers that come inside a plugin without editing the plugin:

[plugins."my-plugin".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search"]

[plugins."my-plugin".mcp_servers.docs.tools.search]
approval_mode = "approve"

default_tools_approval_mode accepts auto, prompt, writes (prompt for tools not marked read-only) and approve.

7. Add MCP servers without a plugin#

For a server that isn't packaged as a plugin, use codex mcp:

# local server started as a command (stdio)
codex mcp add context7 -- npx -y @upstash/context7-mcp

# remote server over Streamable HTTP
codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear          # runs the OAuth flow in your browser

# remote server with a token from an environment variable
codex mcp add example --url https://mcp.example.com/mcp --bearer-token-env-var EXAMPLE_TOKEN

codex mcp list
codex mcp get linear
codex mcp remove linear

Everything after -- is the command that starts a stdio server. Pass environment variables with repeated --env KEY=VALUE.

Or edit ~/.codex/config.toml (or a trusted project's .codex/config.toml) directly:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
startup_timeout_sec = 20

Useful keys: startup_timeout_sec (default 10), tool_timeout_sec (default 60), enabled, required, enabled_tools and disabled_tools. In the desktop app, use Settings > MCP servers > Add server, then Restart. In the IDE extension, use the gear menu > MCP servers, then Restart extension.

Find servers and copy-ready config in the MCP directory.

Signing in with an API key#

If you sign in to Codex with an OpenAI API key, you can browse and install supported OpenAI-curated plugins in the CLI and the desktop app. Some plugins aren't available this way because their connection flow needs OAuth features API-key sign-in doesn't support. Usage shows on the Platform usage page.

Troubleshooting#

Next steps#

• Install plugins in ChatGPT too: How to install, use and remove plugins in ChatGPT.
• Write your own skill: Write a skill for ChatGPT and Codex.
• Browse the plugins directory and MCP directory.