MCP: Extending Codex with Your Own Tools
MCP is the open standard that turns Codex from a code generator into an agent that can read your database, query your APIs, and remember context across sessions.
What MCP Actually Is
Out of the box, Codex can read your files, edit your code, and run shell commands inside the sandbox it was started in. That is already powerful. But the moment you need Codex to do something that lives outside that sandbox — query a live database, search a documentation system, post a message, retrieve stored context from a previous session — you hit a wall.
MCP (Model Context Protocol) is the open standard that removes that wall.
MCP defines a protocol for AI agents to connect to external servers that expose tools, data, and reusable prompts. An MCP server is a lightweight process that runs alongside Codex and advertises what it can do. Codex discovers those capabilities, and when it needs to use them, it calls the server through the protocol. The server handles the actual work — hitting the external API, reading the database, writing to memory — and returns a result.
The mental model: Codex is the reasoning engine. MCP servers are the hands.
The Three Primitives
Every MCP server exposes some combination of three primitive types. Understanding these helps you decide what kind of server you need and what you can expect Codex to do with it.
Tools are actions. A tool is a function the agent can call that does something — reads a file, runs a query, sends a request. Tools are the most common primitive. When you say "I want Codex to be able to search our internal docs," what you really want is a search tool on an MCP server that knows how to talk to your docs system.
Resources are read-only data. A resource is something the server can expose for Codex to consume — a schema, a log file, a document, a configuration snapshot. Resources do not take arguments and do not have side effects. They are the MCP equivalent of GET endpoints.
Prompts are reusable prompt templates. A server can expose prompts that Codex can pull at runtime and inject into its context. This is useful when you have standard instructions (a code style guide, a security checklist) that you want available to the agent without hardcoding them into the system prompt.
Configuring MCP in Codex
Configuration lives in ~/.codex/config.toml. The mcp_servers block is a table where each entry names a server and describes how to start it.
A minimal entry looks like this:
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]
This tells Codex: to start the memory server, run npx -y @modelcontextprotocol/server-memory. When Codex starts, it launches this process, handshakes with it over stdio, and discovers whatever tools and resources the server advertises. The memory server specifically exposes tools for storing and retrieving key-value facts — allowing Codex to remember context across sessions.
For a server that requires credentials, you pass them via the env block:
[mcp_servers.mydb]
command = "node"
args = ["./mcp-servers/database-server.js"]
[mcp_servers.mydb.env]
DATABASE_URL = "postgresql://..."
API_KEY = "sk-..."
Credentials in the env block are passed as environment variables to the server process — they never appear in the agent's context window.
Local vs. remote transports. The examples above are local stdio servers: Codex launches the process itself (command + args) and talks to it over standard input/output. Codex also supports remote MCP servers over streamable HTTP — instead of a command, you give the server's url (with bearer-token or OAuth auth for protected endpoints). Use stdio for tools that run on your own machine, and the HTTP transport to connect to a hosted MCP server you do not launch locally. Check the Codex MCP docs for the exact config keys, since they evolve.
Examples of MCP Servers in Practice
The ecosystem of MCP servers is growing rapidly. A few representative examples illustrate the range of what is possible:
Memory servers give Codex persistent storage. Each session, the agent can store facts, decisions, and context. In the next session, it can retrieve them. Without this, every Codex session starts from scratch — it cannot remember that you prefer a specific code style, that a certain module is off-limits, or that a previous attempt failed for a known reason.
Search servers connect Codex to your documentation, knowledge base, or codebase index. Instead of Codex trying to grep through every file, a search server can answer "find functions that handle payment processing" in milliseconds by querying a prebuilt index.
Messaging servers let Codex post to Slack, Discord, or other channels — useful when you want the agent to notify you when a long task completes, or to drop a summary of what it changed into your team's engineering channel.
These examples span a wide capability range, but they all share the same plumbing: a config entry in ~/.codex/config.toml, a server process that speaks MCP, and a set of tools or resources Codex can call.
The Safety Line: Read vs. Write
Not all tools carry the same risk. The most important mental model for working with MCP tools is the read/write distinction.
READ tools — searching, fetching, querying, reading files — are observational. They do not change anything outside the agent. Codex can call these automatically without asking for your approval. If a read fails or produces wrong output, the worst case is a bad decision on Codex's part, which you catch in the diff review.
WRITE tools — creating, updating, deleting, sending, deploying — have side effects that persist beyond the session. A file written. A message sent. A record deleted. These effects may be irreversible. Codex should surface write actions before executing them and wait for your explicit approval.
This distinction is why thoughtful MCP server design matters. When you build or configure a server, label each tool clearly as read-only or write-capable, and configure appropriate approval behavior for the write tools. The server author cannot make this decision for you — they do not know how sensitive your external system is. You do.
Building a Tool-Extended Codex Workflow
Once you have MCP servers configured, the workflow looks different than a vanilla Codex session. Instead of Codex being limited to what it can observe from your local filesystem and terminal, it can pull live context from your systems and act on them.
A practical example: you assign Codex a task to fix a bug in an API endpoint. In a vanilla session, it reads the source files and makes its best guess about what the endpoint is doing. With MCP servers configured, it can query a search server to find every call site, fetch the relevant schema from a resource server, check a memory server for notes about a previous failed fix attempt, and — after writing the fix — post a summary to a messaging server. All of this happens in one session without you switching tools.
The key discipline: think of MCP configuration as your agent's toolbelt. Every server you add is a capability you are granting. Add the servers your workflow actually needs, understand what each tool does, and enforce the read/write approval boundary rigorously. The goal is not maximum capability — it is maximum trusted capability.