ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Fix “No MCP Servers Configured” in Codex

Fix Codex’s “No MCP Servers Configured” message by checking discovery, adding a server through the CLI or config.toml, and verifying the active client.

By the ScreenshotNeo team1 October 20265 min read

Run codex mcp list first. If it shows no entries, add an MCP server with either codex mcp add <name> -- <server-command> for a local stdio server or codex mcp add <name> --url <server-url> for a remote server. You can also add a [mcp_servers.<name>] table to ~/.codex/config.toml, then run codex mcp list again.

The exact wording “No MCP Servers Configured” is not documented as a single, universal Codex error. Treat it as a discovery or configuration signal first. A configured entry and a healthy, connected server are separate states.

1. Check whether Codex can see any servers

codex mcp list

This command checks the MCP entries available to the Codex installation and user configuration you are using. If the list is empty, add a server before investigating networking, credentials or server startup.

2. Add a local MCP server over stdio

A local stdio server is started by a command on the same machine as Codex. Replace the example command with the startup command documented by your server.

codex mcp add my-local-server -- my-server-command --arg value
codex mcp list

The -- separates Codex’s options from the server command and its arguments. Keep environment variables, working-directory requirements and authentication instructions from the server’s documentation intact.

3. Add a remote MCP server

For a streamable HTTP server, register its URL:

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

OpenAI’s Docs MCP example uses this form and provides read-only access to OpenAI developer documentation. See the official Docs MCP page for that server.

4. Configure the server in config.toml

Instead of the CLI, edit the user-level Codex configuration file:

~/.codex/config.toml

Add a server table using its name as the table key:

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

Then save the file and verify it:

codex mcp list

For a local command, use the command form supported by your Codex version and the server’s documentation. The important structure is the mcp_servers table and a unique server name.

5. Confirm the client context

Codex CLI and the IDE extension share MCP configuration. If the CLI lists a server but another Codex surface does not, check that both are using the same Codex installation and user configuration. The official documentation confirms shared configuration but does not enumerate every client-specific exception.

6. Separate discovery from connection failures

Use this order:

  1. Run codex mcp list.
  2. If no entry appears, add or correct the CLI or TOML configuration.
  3. Run the list command again.
  4. If the entry appears but the server still fails, inspect the server’s own startup, URL, authentication and network requirements.

Do not infer a server outage, invalid credential or network failure solely from the “No MCP Servers Configured” wording. The reviewed official sources establish registration and listing commands, but not a complete diagnostic tree for every runtime failure.

Configuration options at a glance

Route Use when Configuration Verification
CLI, local stdio The server runs as a local process codex mcp add <name> -- <command> codex mcp list
CLI, remote The server exposes a URL codex mcp add <name> --url <url> codex mcp list
TOML You manage configuration as a file [mcp_servers.<name>] in ~/.codex/config.toml codex mcp list

Common errors and fixes

The list is empty after adding a server

Cause: The command may have been run under a different user, installation or configuration context, or the entry was not written successfully.

Fix: Run codex mcp list in the same shell and user context, inspect ~/.codex/config.toml, and add the entry again. Then verify with the list command.

The TOML entry is ignored

Cause: The table name or TOML syntax does not match the expected [mcp_servers.<name>] structure.

Fix: Check brackets, quoting and indentation, save the file, and rerun codex mcp list. Use the official example as a known-good starting point.

The server appears but does not respond

Cause: Discovery succeeded, but the process, URL, authentication or network path may be incorrect.

Fix: Follow the server provider’s startup and authentication documentation. Confirm the command or URL independently and check the server’s own logs.

CLI and IDE show different results

Cause: They may not be using the same Codex installation or user-level configuration.

Fix: Confirm the active user, installation and ~/.codex/config.toml path for both surfaces.

The exact message does not match the documentation

Cause: The phrase is not documented as a universal Codex error and may vary by surface or version.

Fix: Start with the observable state: whether codex mcp list contains an entry. Diagnose registration first, then connection health.

Or skip the browser setup

If your MCP workflow needs website screenshots for an agent, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. It also exposes a one-call screenshot API.

See the ScreenshotNeo API documentation for all options. cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups and chat widgets are removed before the shot. Bot checks, blank pages, failed loads and cache hits are not billed, and response headers report the page verdict and billing result. ScreenshotNeo includes 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

Performance, reliability and cost notes

  • Discovery: codex mcp list is the quick configuration check; it does not prove that a server is healthy.
  • Local versus remote: Local stdio requires a runnable command in the active environment. Remote setup requires a reachable URL and whatever authentication the server specifies.
  • Configuration scope: The documented user-level file is ~/.codex/config.toml. A different user or installation can therefore produce a different server list.
  • Screenshot costs: ScreenshotNeo bills only clean shots. Bot checks, blank pages, timeouts, failed loads and cache hits cost nothing; each response includes X-Page-Verdict and X-Billed headers.

FAQ

Where does Codex store MCP server configuration?

The documented user-level location is ~/.codex/config.toml, using [mcp_servers.<name>] tables.

What command confirms that a server is registered?

Run codex mcp list.

Can I use a server without running a local process?

Yes. Register a remote server with codex mcp add <name> --url <server-url>.

Does a listed server guarantee that tools will work?

No. Listing confirms configuration discovery. Startup, authentication, network and server-specific failures require separate diagnosis.

Do Codex CLI and the IDE extension use separate MCP lists?

The official documentation says they share MCP configuration. If results differ, verify that both use the same installation and user configuration.

Keep reading