Skip to content
Lesson 6 of 786% of the course

Codex MCP servers, skills and custom agents

Add an MCP server to Codex's config.toml, write a SKILL.md Codex picks up on its own, make a custom agent in .codex/agents and set defaults for subagents, in Config Studio for Codex.

Config Studio for Codex courseAdvanced4 steps3 min
Open Config Studio for Codex
Nothing loads from YouTube until you press play. Then Google receives your IP address and may set its own storage. Narrated with an AI-generated voice. Privacy

Codex can do more than read and edit files: an MCP server gives it outside tools, a skill gives it a recipe it loads when a task matches, and a custom agent is a helper it hands work to. Each lives in its own file and format. This lesson writes one of each.

Add an MCP server

Open Config Studio for Codex and press MCP servers. One server is one [mcp_servers.<name>] table in config.toml:

  1. Name it: a short name, such as docs.
  2. Command and Arguments for a local server (npx, then -y and the package on the next line), or URL for a remote one. Bearer token comes from names the environment variable that holds its token, so the token itself never goes in the file.
  3. Only these tools keeps the server to the tools you list; Never these tools blocks some.
  4. Before one of its tools runs decides whether Codex asks: auto, prompt, writes or approve.
A local server: a command, its arguments, and only the tools you need.

Give a slow server more time with Startup timeout (s), and turn on Fail startup if it cannot start for a server Codex must not run without.

Write a skill

Press Skills. A skill is a folder with a SKILL.md:

  • Where it lives: yours in ~/.agents/skills, or the repository's in .agents/skills so everyone gets it.
  • Name: the folder name, such as release-notes. You can call it by name with $release-notes.
  • When to use it: the line Codex reads to decide whether the skill fits a task. Say what it does and when; most of the work is here.
  • Instructions: the steps, in Markdown.
The description decides when Codex loads it.

Leave Codex may pick it on its own on to let Codex load it when a task matches; off, it runs only when you name it.

Make a custom agent

Press Custom agents. An agent is one TOML file Codex can hand work to:

  • Where it lives: the repository's .codex/agents, or yours in ~/.codex/agents.
  • Name, When to use it and Its instructions: who it is, when Codex should use it and how it works.
  • Model, Reasoning effort and Sandbox only if it differs from the session that starts it. A reviewer is safer read-only.
One agent, one file; what it leaves out comes from the session.

A name that matches a built-in agent (default, worker, explorer) replaces it.

Set defaults for subagents

Subagent defaults writes the [agents] table: Most agents open at once, Default model for agents and Default effort for agents. A custom agent's own file beats these for that agent.

Next: install and share a Codex setup, from a starter pack to one install script.

Your progress stays in this browser only.
Contact