# Use plugins and MCP servers in Codex

> Install plugins in the Codex CLI with /plugins or codex plugin add, add marketplaces, enable plugins per project, and connect MCP servers through config.toml.

Published: 2026-10-04 · By: Divy Chaurasia · Level: beginner · Time: 15 min · Tags: codex, plugins, mcp

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:

```bash
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:

| Surface | Plugins | MCP servers |
| --- | --- | --- |
| Codex CLI | Yes (`/plugins`) | Yes |
| Codex in the ChatGPT desktop app | Yes (**Plugins** tab) | Yes |
| IDE extension | No | Yes |

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:

```text
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 <kbd>Space</kbd> 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.

> **plugin:** [GitHub](https://chatgptplugins.directory/plugins/github): Triage PRs, issues, CI, and publish flows
## 2. Install from the command line

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

```bash
# 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>/`.

> **plugin:** [Linear](https://chatgptplugins.directory/plugins/linear): Plan and build products
## 3. Add more marketplaces

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

```bash
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:

```bash
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:

```bash
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](/tutorials/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`:

```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:

```toml
[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`:

```bash
# 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`.

> **MCP server:** [Context7](https://chatgptplugins.directory/mcp/context7): Pull up-to-date, version-specific library docs into your coding agent
Or edit `~/.codex/config.toml` (or a trusted project's `.codex/config.toml`) directly:

```toml
[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](/mcp).

## 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

| Problem | Fix |
| --- | --- |
| No plugins in the IDE extension | Expected. Use the CLI or the desktop app. |
| Installed plugin does nothing | Start a new session, then check it's toggled on in `/plugins`. |
| Project `enabled = true` ignored | Trust the project; untrusted projects skip `.codex/config.toml`. |
| Marketplace entry missing | Codex skips entries whose source it can't resolve. Check the path or Git ref, then run `codex plugin marketplace upgrade`. |
| MCP server times out on start | Raise `startup_timeout_sec`, and run the command by hand to see errors. |
| OAuth server shows as unauthenticated | Run `codex mcp login <name>`. |

## Next steps

- Install plugins in ChatGPT too: [How to install, use and remove plugins in ChatGPT](/tutorials/install-plugins-in-chatgpt).
- Write your own skill: [Write a skill for ChatGPT and Codex](/tutorials/write-a-skill-for-chatgpt-and-codex).
- Browse the [plugins directory](/plugins) and [MCP directory](/mcp).

## Listings in this tutorial

- [GitHub](https://chatgptplugins.directory/plugins/github.md): Triage PRs, issues, CI, and publish flows
- [Linear](https://chatgptplugins.directory/plugins/linear.md): Plan and build products
- [Context7](https://chatgptplugins.directory/mcp/context7.md): Pull up-to-date, version-specific library docs into your coding agent

---
Source: https://chatgptplugins.directory/tutorials/use-plugins-in-codex · Index: https://chatgptplugins.directory/llms.txt · Independent and community-run. Not affiliated with or endorsed by OpenAI. ChatGPT is a trademark of OpenAI.