# MCP, skills, plugins and hooks in Codex: extending agents with external tools

URL: https://opcaios.org/en/blog/mcp-skill-va-hooks-trong-codex
Date: 2026-11-03
Author: Lê Quốc Nghĩa

MCP in Codex is how OpenAI's Codex programming agent calls tools and reads data from external MCP servers, declared via the `codex mcp` command or the `[mcp_servers.<name>]` table in the `config.toml` file. Besides MCP, Codex has three other extension mechanisms: skill (instruction packages that can include scripts), plugin (pre-packaged bundles of many things, installed from the plugin marketplace) and hooks (commands that run at specific points in the session lifecycle). This post is based on Codex documentation on learn.chatgpt.com and the `--help` output of Codex CLI version 0.162.1, read on 03/11/2026; features may change across versions. This post makes no claims about the safety or effectiveness of any utilities and does not provide sample hook configurations because we have not yet written any blocking hooks. The post covers how to add MCP servers, skills, plugins, hook points, a comparison table, risks, a decision tree and real experience from OPCAIOS. If you're not yet clear on MCP, first read [What is MCP](/blog/mcp-la-gi).

![A diagram of four ways to extend Codex: MCP server connects external tools via codex mcp and config.toml, skill is a SKILL.md file in .agents/skills, plugin bundles skills, MCP servers and hooks installed from the plugin marketplace, hooks run at points like SessionStart, PreToolUse, PostToolUse and Stop](https://opcaios.org/images/blog/mcp-skill-va-hooks-trong-codex/so-do.webp)
*Four mechanisms to extend Codex and where to declare each. Diagram: OPCAIOS.*

## How do I add an MCP server to Codex using the codex mcp command?

Adding an MCP server to Codex via the command line is the quickest way: the `codex mcp add` command writes the declaration to `~/.codex/config.toml` instead of editing by hand. According to `codex mcp --help` from Codex CLI 0.162.1 (run on 03/11/2026), the command group includes `list`, `get`, `add`, `remove`, `login` and `logout`. The `add` command takes a name, then either `--url` for a streamable HTTP server, or `--` followed by a command to start a local server (stdio). The `--env KEY=VALUE` flag is only for stdio servers, while `--bearer-token-env-var` is only for HTTP servers and takes the name of an environment variable holding the token, not the token itself. Example from Codex MCP documentation:

```bash
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
codex mcp login <server-name>
```

In Codex's terminal interface, type `/mcp` to see which servers are running.

### What keys does an MCP server declaration in config.toml contain?

Declaration in `config.toml` gives finer control than the `add` command. According to Codex's MCP page (learn.chatgpt.com/docs/extend/mcp, read on 03/11/2026), each server is a `[mcp_servers.<name>]` table. A stdio server needs `command`, and can have `args`, `env`, `cwd`. An HTTP server needs `url`, and can have `bearer_token_env_var` and `http_headers`. Notable common keys: `startup_timeout_sec` (default 10 seconds), `tool_timeout_sec` (default 60 seconds), `enabled`, `required`, `enabled_tools` and `disabled_tools`.

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

[mcp_servers.vi-du-http]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "VI_DU_TOKEN"
enabled_tools = ["search"]
```

The second server is a hypothetical example. The documentation notes that OAuth client secrets, if declared, will appear in lowercase in the file, so keep the file private and outside of git.

## What is a skill in Codex and where do I put it?

A skill in Codex is a directory containing a `SKILL.md` file (instruction plus metadata), optionally with `scripts/`, `references/` and `assets/`, helping Codex carry out a repeatable process correctly. According to the build-skills page in Codex documentation (read on 03/11/2026), the beginning of `SKILL.md` must have `name` and `description`, and skills follow the open agent skills standard. Codex looks for skills in four layers:

1. Repository: `.agents/skills` in the current directory, parent directory and repository root.
2. User: `$HOME/.agents/skills`.
3. Administrator: `/etc/codex/skills`.
4. System: bundled with Codex, including `skill-creator` and `skill-installer`.

Call a skill with `/skills` or type `$` followed by the name; Codex also auto-selects a skill when it matches `description`. Codex only loads the name and description first, reading the full `SKILL.md` when that skill is chosen; the initial list by default takes up at most 2% of the context window. So `description` should be clear about when to use it and when not to. The general concept of skills appears in the post [What is skill and how to use skill](/blog/skill-la-gi-cach-dung-skill).

## How does Codex Plugin and its plugin marketplace work?

A Codex plugin is a pre-packaged set of capabilities to install once: according to the Plugins page in the Codex documentation (read on 03/11/2026), a plugin can include a skill, MCP server, browser utility, and hooks. Codex CLI and desktop application can use plugins, but IDE utilities cannot. There are three ways to install and manage:

1. In Codex CLI, type `/plugins`, install from a configured marketplace, then open a new session.
2. Use the command: `codex plugin add <plugin>@<marketplace>` to install, `codex plugin list` to view, `codex plugin remove` to uninstall (per `codex plugin --help`).
3. Add a custom marketplace: `codex plugin marketplace add` accepts a local path, `owner/repo`, or Git URL; has `upgrade` to refresh and `remove` to delete.

The Plugins directory has an OpenAI tab, a workspace tab, and a personal tab. To compare with commands, skills, plugins, and MCP on [Claude Code](/tien-ich/claude-code), see the post [slash command, skill, plugin or MCP](/blog/slash-command-skill-plugin-hay-mcp); this post does not repeat that section.

## At what points do hooks in Codex run?

Hooks in Codex are commands you declare that run automatically at fixed points in a session, unlike guidance in AGENTS.md which is only a suggestion to the model. According to the Hooks page (learn.chatgpt.com/docs/hooks, read on 03/11/2026), Codex has 14 points: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, `Stop`, `Interrupt`, `PreModelRequest`, and `PostModelRequest`. Hooks are placed in `~/.codex/hooks.json`, in the `[hooks]` table of `config.toml`, or in `.codex/` of the repository; plugins also carry hooks along. Three important points:

1. Only some points can block operations: `PreToolUse` can reject a command, `UserPromptSubmit` blocks a prompt, `PermissionRequest` allows or denies; exit code 2 with a reason is one way to block.
2. `PostToolUse` blocks by replacing the result only, it does not undo the command already run; background hooks and points like `SessionEnd`, `Interrupt` cannot block.
3. Hooks not created by an admin must be reviewed and trusted before running; modifying a hook requires trusting it again. Use `/hooks` to view, trust, or disable.

Hooks are on by default, disable with `hooks = false` in `[features]`. For hooks on Claude Code, see [hooks in Claude Code](/blog/hooks-trong-claude-code).

## Compare MCP, skill, plugin, and hooks in Codex

Four mechanisms solve four different problems. Summary table according to documentation read on 03/11/2026:

| Mechanism | Solves what problem | Declare where | Who decides when to run |
|---|---|---|---|
| MCP server | Let Codex call tools, read external system data | `codex mcp add`, `[mcp_servers.<name>]` | Model chooses to call tools, by approval mode |
| Skill | Teach Codex a repeatable process | `SKILL.md` in `.agents/skills` | You call with `$`, or model chooses by description |
| Plugin | Install a package of skill, MCP, hooks at once | `/plugins`, `codex plugin add` | Depends on components inside |
| Hook | Run a command surely at a point, can block | `hooks.json`, `[hooks]` | System, each time the point is reached |

Way to remember: MCP is an assistant's hand, skill is a notebook, plugin is a packed box, hook is a latch.

## What are the risks when installing strange utilities for Codex?

The main risk when installing strange MCP server, skill, or plugin is giving code from others the power to run on your machine and read the data Codex can read. Five specific risks:

1. MCP server stdio is a program that runs on your machine; commands like `npx -y` download and run the latest package without asking again.
2. Tool descriptions and responses from MCP server go straight into model context, so they can contain prompt injection instructions.
3. Skill can come with scripts; Codex runs that script in a sandbox and current approval, but if you already gave broader permissions then the script has those permissions.
4. Plugin packs many things at once, including hooks that must be reviewed and trusted before running.
5. Token and client secret declared in `config.toml` leak if the file is committed.

Measures: install from sources where you can read the code, lock package versions, use `enabled_tools` to turn on only needed tools, keep tokens in environment variables, maintain strict approval when trying. See also [security when using AI to write code](/blog/bao-mat-khi-dung-ai-viet-code).

## Decision Tree: Which Mechanism Should I Use?

Ask in sequence, stop at the first question answered "yes":

1. Must this happen for certain, regardless of which decision model (blocking dangerous commands, logging)? Use a hook.
2. Does Codex need to read or write to an external system (GitHub, database, calendar)? Use an MCP server.
3. Is this a multi-step process you often explain again? Write a skill.
4. Do you need to carry skills, MCP, and hooks to another machine or share with a team? Package it as a plugin, or install a ready-made plugin.

If it's just a general rule like "reply in Vietnamese", put it in [AGENTS.md](/blog/agents-md-la-gi) and you're done, no mechanism needed.

## OPCAIOS Experience

OPCAIOS uses Codex CLI version 0.162.x and the Codex desktop application. These things are real, checked on 03/11/2026:

1. All enabled plugins come from OpenAI's plugin marketplace: browser, visualization, Gmail, Google Calendar, Slack, documents, PDF, spreadsheets, and presentations. The machine also has Codex's Computer Use application installed. We haven't tracked the frequency of using each plugin yet, so we just say "enabled".
2. Codex hooks are configured at session start, send prompt, before and after tools, permission request, subagent, and stop, but only to report session status to a terminal management tool. No hooks block commands yet.
3. A plugin code review folder exists but is empty, so we can't claim we use Codex for code review regularly.

What we haven't done: haven't measured which plugins save time, haven't put any protective hooks in place of manual discipline.

## Frequently Asked Questions

### If I add an MCP server to Codex CLI, can I use it in the desktop application?

Yes, according to Codex MCP documentation read on 03/11/2026: the desktop application, Codex CLI, and IDE utilities all share the MCP configuration in `~/.codex/config.toml`, so adding it once with `codex mcp add` makes it available to all three. The web version of ChatGPT doesn't read local config files; accessing MCP tools from the web goes through plugins. Configuration in `.codex/config.toml` in a project only takes effect when the project is trusted.

### Can I reuse Claude Code skills in Codex?

The format is similar: both use a directory with `SKILL.md` containing `name` and `description`, and Codex documentation says skills are based on the open agent skills standard. The difference is location: Codex looks in `.agents/skills` in the repository and `$HOME/.agents/skills`, not Claude Code's own directory. Skills that call tools specific to one agent need adjustment; we haven't verified sharing them.

### Can Codex hooks block dangerous commands?

Possibly, at the right point. According to the Hooks page read on 03/11/2026, the `PreToolUse` hook can reject a command before it runs, and the `PermissionRequest` hook can reject a permission request; exit code 2 with a reason is one way to block. The `PostToolUse` hook can't undo a command that's already run. Background hooks can't block anything, and all hooks must be trusted before they run. OPCAIOS hasn't written blocking hooks so we don't provide an example.

### Should I install many plugins at once?

No, don't install everything you see. Each plugin may carry MCP servers, skills, and hooks—meaning it adds tools for the model to choose, adds descriptions that take up context, and adds code that runs on your machine. Enable a plugin when you have a specific task, read what it includes, check hooks in `/hooks`, remove it with `codex plugin remove` when you're done. The documentation notes that uninstalling a plugin in ChatGPT doesn't automatically close the plugin's MCP connection.

### Where should someone who doesn't know programming start extending Codex?

Start with AGENTS.md for general rules, then install one official plugin from the OpenAI tab in the Plugins folder for what you actually need, instead of writing your own MCP server or hook. Once familiar, try `$skill-creator` to let Codex compose a skill from your description. Save hooks for last since they need shell command knowledge. The article [safe process for people who don't know code](/blog/tac-tu-lap-trinh-cho-nguoi-khong-biet-code-quy-trinh-an-toan) has the fundamentals. For direct guidance, see [OPCAIOS's AI application training course](/services/dao-tao-ung-dung-ai).

*Source: Codex documentation on learn.chatgpt.com (pages extend/mcp, build-skills, plugins, hooks; redirected from developers.openai.com/codex) and `codex --help`, `codex mcp --help`, `codex plugin --help` from Codex CLI 0.162.1, read on 03/11/2026. Not verified: detailed JSON structure of hooks.json, sharing skills between Codex and Claude Code, plugin behavior in IDE utilities in later versions; features may change across versions. Experience is OPCAIOS's.*
