index.htm

Codex MCP: Connect Tools and Verify the Setup

Put together with AI based on my original idea and edits.

AI-translated from Russian. Read the original.

On this page

Setting up MCP in Codex starts with a specific operation: find a documentation page, read a task, or check a service’s state. Once that operation is clear, choosing a server, limiting access, and seeing whether the connection works becomes easier.

It helps to distinguish three results from the start: the configuration is saved, the server is reachable, and the required operation is complete. Each needs its own check. An entry in the server list confirms only the first stage.

What MCP, skills, and project instructions do

MCP gives the agent an interface to tools: which actions are available, which arguments they accept, and what results they return. A specific server performs the action using its own connections and permissions.

A skill describes a repeatable workflow. Its SKILL.md can explain when to find a document, how to select the right result, and what confirms completion. A skill can use MCP, ordinary files, or commands. Having instructions does not itself install a server or grant account access.

AGENTS.md is a useful place for project rules: where the source lives, how publishing works, and which checks are required. That agreement helps keep the workflow consistent across tasks. OSS Agent Playbook provides a practical example of organizing these rules.

First connection: a documentation server

The public OpenAI documentation server is suitable for a first attempt: you can check search and reading without access to work data. Run in your terminal:

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

For manual configuration, the equivalent entry in ~/.codex/config.toml is:

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Choose one way to add it. codex mcp get openaiDeveloperDocs helps inspect the saved entry; review its output locally, particularly for other servers that use authentication.

After changing MCP configuration, start a new CLI session and open /mcp. Then give it a verifiable task: “Find the MCP description in the official Codex documentation and read the page. Return the link and briefly name the supported transports.” The result should include an actual tool call and a source that was read.

Local process or HTTP

For a STDIO server, Codex starts a process using the configured command. The executable, arguments, working directory, and environment all matter. Establish how the server writes diagnostics and where to look for startup errors.

Streamable HTTP connects to a service address. Check reachability, TLS, authentication, and permissions. Using HTTP alone does not determine which files the server can see: that depends on where it runs and how its tools are implemented.

Before connecting a file tool, establish which machine holds the files. Before connecting a browser, establish which browser and profile are available. This gives “read this file” an unambiguous meaning and prevents a local path from becoming a request to a different machine.

Permissions and evidence of completion

Start with a read operation and the smallest necessary access scope. Keep secrets out of the published example and repository. HTTP configuration supports obtaining a bearer token from an environment variable. If the server uses OAuth, its support determines the sign-in flow; the CLI provides codex mcp login <server-name>.

A small reversible change is useful for testing the first write: create a test task, read it using the returned identifier, then delete it. Publishing benefits from another sequence: write the change, open its published address, and check the content. A response saying “command accepted” leaves the outcome unverified.

This shift toward checking state relates to how Codex takes the IDE’s place. Choosing suitable evidence remains part of engineering judgment.

If the connection does not work

Locate the failure and change one possible cause at a time:

Save a short description: the operation, expected outcome, actual response, and reproduction steps. Leave out tokens and complete private responses. That record will help with the next failure and will not depend on a single conversation with the agent.

Frequently asked questions

Can a skill work without MCP?

Yes. A skill can describe a workflow using Markdown, local files, or available commands. MCP is needed when that workflow uses an MCP server’s tools.

Why does codex mcp list show the server when the task still fails?

A saved entry does not establish successful authentication or execution of a particular tool. Check the active connection through /mcp, then make a small read request.

When does Codex CLI actually need a restart?

After changing connection configuration, starting a new session and checking its tool set is a safe approach. New requests to an already working server do not themselves require a restart. Skill changes are usually detected automatically; if a skill does not appear, check its description and location, then restart the CLI.

How do you know setup is complete?

The agent performs the required operation in the correct environment, and the result can be independently read or opened. The connection method, access boundaries, and a short health check are recorded for future tasks.

Syntax and capabilities were checked against documentation on November 2, 2026: the official OpenAI documentation server, Codex CLI MCP documentation, and skills documentation. Check codex mcp --help for the commands supported by your installed version.