›_ Codex Issues
Codex Issues / #5161

Codex fails to detect and use configured MCP gateway, repeatedly guessing binaries instead

Resolved 💬 12 comments Opened Oct 14, 2025 by stnwlls Closed Oct 26, 2025
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What version of Codex is running?

codex-cli 0.46.0

Which model were you using?

gpt-5-codex with high reasoning

What platform is your computer?

Darwin 25.0.0 arm64 arm

What steps can reproduce the bug?

Prereqs

  • Docker Desktop with the MCP Toolkit enabled and Notion MCP installed.
  • Codex CLI installed and configured via ~/.codex/config.toml.
  • A Docker MCP server entry.

My config snippet

[mcp_servers.docker_desktop]
command = "docker"
args = [
  "mcp",
  "gateway",
  "run"
]

MCP list via Codex CLI

/mcp

🔌  MCP Tools

• Server: docker_desktop
    • Status: enabled
    • Auth: Unsupported
    • Command: docker mcp gateway run

Steps

  1. Run Codex CLI and issue a task that explicitly asks to use the Notion MCP, e.g.:

``bash
codex> "Using Notion MCP, open [page] and summarize it"
``

  1. Observe that Codex fails to discover the Notion MCP via Docker and instead attempts to call local binaries and search the filesystem.
Note: Before this bug, the above prompt was enough for Codex to know that it needed to access Notion through the Docker MCP setup.

What is the expected behavior?

The expected behavior covers both the discovery and introspection phases when interacting with a Docker-backed Notion MCP through the Codex CLI.

Discovery:
When Codex receives a request that explicitly or implicitly mentions an MCP such as Notion, it should follow a clear, step-by-step process to resolve and connect to the appropriate service:

  1. Check the user's configuration file (e.g., ~/.codex/config.toml for declared MCP servers, including any Docker-backed entries.
  2. If a Docker MCP entry is found, Codex should immediately attempt to connect to the Docker MCP gateway using this configuration.
  3. Codex should avoid any fallback behaviors that probe for local executables named notion, mcp, notion_mcp, mcp-notion, or perform ad-hoc filesystem searches for MCP-related content.
Even if the Docker MCP entry isn't found, if it checked the configuration file first, it would know that Notion didn't exist, and inform the user that it was not able to find any Notion MCP server entries.
  1. It should also avoid unnecessary attempts to list Python packages or run unrelated commands to discover MCP tools.
  2. This process should be automatic and transparent to the user, enabling seamless MCP discovery and connection without manual intervention or explicit commands.

Tool introspection:
Once connected to the Docker MCP gateway, Codex should automatically resolve the MCP connection and load the available tools exposed by the registry. This should happen without manually runing commands like docker mcp tools list or docker mcp tools inspect to "unlock" or discover the tools. These introspection commands should remain available as optional diagnostics or debugging aids, but they must not be prerequisites for the CLI to recognize and utilize the MCP. The CLI should maintain an internal cache or state reflecting the available tools, updating it as needed, so that tool invocation commands can be issued directly and reliably.

User experience expectations:
On startup and during usage, the CLI should proactively check the configuration file and auto-detect any accessible MCP servers, including those backed by Docker. This minimizes the need to perform manual discovery steps or troubleshoot why an MCP is not being recognized. The CLI should prioritize configured MCP entries over local binaries or heuristics, ensuring a smooth and predictable user experience.

What do you see instead?

  • Codex ignored the Docker MCP config initially and attempted to:
  • run notion, mcp, npx notion, notion_mcp, mcp-notion (all missing),
  • search the working directory and $HOME for Notion/MCP content,
  • list packages via pip/python3 -m pip.
  • Only after being explicitly told that Notion MCP exists "through Docker" did it pivot to docker mcp … subcommands, after which the Notion tool catalog became visible.
  • Additionally, when prompted that Docker MCP access was defined in its configuration file, Codex proceeded to manually locate and read the file rather than automatically recognizing and applying the existing configuration.

Below is the actual session output up to the point where it began taking action:

› Using Notion MCP, can you redefine my Visual Identity Lab page to better optimize it and make it clearer. Create a beautiful, engaging, and useful Visual Identity. Before you start, you can use the Notion MCP to familiarize yourself with my Notion. Read every page.

• Explored
  └ List ls
    Search Notion MCP
    Read AGENTS.md
    Search MCP
    List ls -a
    Search Notion

• Ran notion --help
  └ bash: notion: command not found

• Ran mcp --help
  └ bash: mcp: command not found

• Ran npx notion --help
  └ npm error could not determine executable to run
    npm error A complete log of this run can be found in: /Users/austinwells/.npm/_logs/2025-10-14T03_24_06_033Z-debug-0.log

• Explored
  └ Search Notion
    Search Notion MCP in ..
    Search find . -maxdepth 2 -type d
    Search notion

• Ran env | sort
  └ __CF_USER_TEXT_ENCODING=0x1F5:0x0:0x0
    __CFBundleIdentifier=dev.warp.Warp-Stable
    … +7 lines
    XPC_FLAGS=0x0
    XPC_SERVICE_NAME=0

• Ran pip list | grep -i notion
  └ bash: pip: command not found

• Ran python3 -m pip list | grep -i notion
  └ (no output)

• Explored
  └ Search *mcp* in ..
    Search *notion* in ..
    List ..
    Search *notion* in Scripts

• Ran notion_mcp --help
  └ bash: notion_mcp: command not found

• Ran mcp-notion --help
  └ bash: mcp-notion: command not found

• Explored
  └ Search *notion* in ~
    List notion-mcp
    Read package.json

■ Conversation interrupted - tell the model what to do differently

› You have access to the Notion MCP through Docker as defined in your config file.

• Explored
  └ Search *codex* in ~
    List .codex
    Read config.toml
    Search notion in .codex

• Ran docker mcp gateway run --help
  └ Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

    … +7 lines
          --watch                             Watch for changes and reconfigure the gateway (default true)

• Explored
  └ Read config.yaml, docker-mcp.yaml
    Search notion in docker-mcp.yaml
    Search notion in docker-mcp.yaml
    Read docker-mcp.yaml, registry.yaml
    List mcp

• Ran docker mcp --help
  └ Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

    … +7 lines
      version     Show the version information

• Ran docker mcp client --help
  └ Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

    … +5 lines
      ls                  List client configurations

• Ran docker mcp tools --help
  └ Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

    … +7 lines
      list        List tools

• Ran docker mcp tools list --format json
  └ [
      {
    … +7 lines
      }
    ]

• Ran docker mcp tools call --help
  └ Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

    Usage: docker mcp tools call

• Ran docker mcp tools call --help --verbose
  └ Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

    Usage: docker mcp tools call

• Ran docker mcp tools inspect notion:API-post-search --format json
  └ tool notion:API-post-search not found

• Ran docker mcp tools list | head
  └ 193 tools:
     - API-create-a-comment - Notion | Create comment
    … +6 lines
     - API-patch-block-children - Notion | Append block children
     - API-patch-page - Notion | Update page properties

(We stop here because the next command actually succeeds and the model begins taking action.)

Additional information

  • Environment hints (from the session): macOS (Warp terminal), no local pip in PATH for the session, fresh shell.
  • docker mcp help output was accessible, confirming the Docker MCP Toolkit was installed.
  • First successful Notion interaction observed after discovery: docker mcp tools call API-get-self returned the Notion bot profile for workspace.
  • Hypothesis (discovery): Codex CLI currently prioritizes local executables and file heuristics before honoring Docker MCP entries in config.toml. When no local binaries are present, it doesn’t automatically fall back to the Docker MCP gateway.

View original on GitHub ↗

12 Comments

github-actions[bot] contributor · 9 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #3666
  • #3324

Powered by Codex Action

stnwlls · 9 months ago

I've reviewed the linked issues and can confirm this report is not a duplicate.

The key difference is the stage at which the failure occurs:

  • My issue describes a Discovery Failure. As shown in the logs, Codex fails to read its own configuration and cannot find the Docker MCP at all.
  • Issue #3666 is an Execution Failure. Codex successfully finds the tool and creates the correct command but fails to run it.
  • Issue #3324 is a Connection Failure (a timeout), which occurs after the tool has already been discovered.

My bug occurs at a more fundamental step in the process, before the failures described in the other issues could even happen.

fallonou1999 · 9 months ago

I found this issue too, I think it has something to do with model reasoning ability, because after I switched model to gpt-5-high(before was gpt-5-codex-high), it never happens again

stnwlls · 9 months ago
I found this issue too, I think it has something to do with model reasoning ability, because after I switched model to gpt-5-high(before was gpt-5-codex-high), it never happens again

It seems they changed it so the only models available are

  • gpt-5-codex
  • gpt-5

There's no reasoning level anymore!

fallonou1999 · 9 months ago
> I found this issue too, I think it has something to do with model reasoning ability, because after I switched model to gpt-5-high(before was gpt-5-codex-high), it never happens again It seems they changed it so the only models available are gpt-5-codex gpt-5 There's no reasoning level anymore!

Actually when you switch it, it would show up options to select reasoning level, and you can set it in ~/.codex/config.toml with “model_reasoning_effort = "high"”

stnwlls · 9 months ago
> > I found this issue too, I think it has something to do with model reasoning ability, because after I switched model to gpt-5-high(before was gpt-5-codex-high), it never happens again > > > It seems they changed it so the only models available are > > gpt-5-codex > gpt-5 > > There's no reasoning level anymore! Actually when you switch it, it would show up options to select reasoning level, and you can set it in ~/.codex/config.toml with “model_reasoning_effort = "high"”

Ah, you're right. I am on gpt-5-codex with high reasoning. I'll try the non-codex version. Thank you!

gpeal contributor · 9 months ago

There are two separate things here:

  1. Does the Docker MCP gateway work?
  2. What does the model do when a tool call fails or it can't find the right tool.

Let's keep this issue focused on the first. The behavior for what the model will do in that sitaution is not something tangible to focus on in this PR but something I'll take to our research team for further discussion.

I just gave this a shot with 0.47 and had no issues using the docker mcp gateway to call the Notion MCP. Could you maybe try again?

<img width="2976" height="404" alt="Image" src="https://github.com/user-attachments/assets/9756ccb5-78e1-4bd4-873b-97a6b7013fd2" />

stnwlls · 9 months ago
There are two separate things here: 1. Does the Docker MCP gateway work? 2. What does the model do when a tool call fails or it can't find the right tool. Let's keep this issue focused on the first. The behavior for what the model will do in that sitaution is not something tangible to focus on in this PR but something I'll take to our research team for further discussion. I just gave this a shot with 0.47 and had no issues using the docker mcp gateway to call the Notion MCP. Could you maybe try again? <img alt="Image" width="2000" height="404" src="https://private-user-images.githubusercontent.com/1307745/502780785-9756ccb5-78e1-4bd4-873b-97a6b7013fd2.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NjA3NDA1MTYsIm5iZiI6MTc2MDc0MDIxNiwicGF0aCI6Ii8xMzA3NzQ1LzUwMjc4MDc4NS05NzU2Y2NiNS03OGUxLTRiZDQtODczYi05N2E2YjcwMTNmZDIucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI1MTAxNyUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNTEwMTdUMjIzMDE2WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZmMzMTNjNWJlZGY3Njc2OWRkNmNjMzkyMmRhZjJlOTI3ODhhZmZkM2Y3MDU3YTcyMzcyZTI0ODg0ZDI4ZDY1NyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.tdKtgWRBsKKomZcYpuS_QmuyDudnvjohSpN1FQxieZc">

Understood! Thank you, I’ll try it again with 0.47.

To clarify the behavior I’m describing: the Docker MCP gateway itself does work when I explicitly tell the model to use it. It connects and can successfully call the Notion MCP. The issue isn’t that the gateway fails, but that the model doesn’t automatically recognize or use it unless explicitly instructed.

In other words, if I simply ask it to “use the Notion MCP,” it doesn’t appear to check its configured MCP servers first. Instead, it tries to locate local binaries or search the filesystem before eventually being told to use Docker. Once directed, everything works as expected.

So the gateway functionality looks fine; the concern is about discovery — how the model determines that it already has access to the MCP through its config, without needing to be told directly.

gpeal contributor · 8 months ago

@stnwlls Could you try with 0.48? It includes some work that might help here.

stnwlls · 8 months ago
@stnwlls Could you try with 0.48? It includes some work that might help here.

Hello, I tried with 0.48 and it was not successful.


╭─────────────────────────────────────────────────╮
│ ✨ Update available! 0.48.0 -> 0.50.0            │
│ Run brew upgrade --cask codex to update.        │
│                                                 │
│ See full release notes:                         │
│ https://github.com/openai/codex/releases/latest │
╰─────────────────────────────────────────────────╯

╭────────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.48.0)                      │
│                                                │
│ model:     gpt-5-codex high   /model to change │
│ directory: ~                                   │
╰────────────────────────────────────────────────╯

  To get started, describe a task or try one of these commands:

  /init - create an AGENTS.md file with instructions for Codex
  /status - show current session configuration
  /approvals - choose what Codex can do without approval
  /model - choose what model and reasoning effort to use
  /review - review any changes and find issues

                                                                                                                                                                                              

› Using Notion MCP, can you redefine my Visual Identity Lab page to better optimize it and make it clearer. Create a beautiful, engaging, and useful Visual Identity. Before you start, you
  can use the Notion MCP to familiarize yourself with my Notion. Read every page.


• Called codex.list_mcp_resources({})
  └ {"resources": []}

• Called codex.list_mcp_resource_templates({})
  └ {"resourceTemplates": [{"server": "docker_desktop", "name": "Repository Content", "uriTemplate": "repo://{owner}/{repo}/contents{/path*}"}, {"server": "docker_desktop", "name":
        "Repository Content for specific branch", "uriTemplate": "repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}"}, {"server": "docker_desktop", "name": "Repository Content for
        specific pull request", "uriTemplate": "repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}"}, {"server": "docker_desktop", "name": "Repository Content for specific
        tag", "uriTemplate": "repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}"}, {"server": "docker_desktop", "name": "Repository Content for specific commit", "uriTemplate": "repo://
        {owner}/{repo}/sha/{sha}/contents{/path*}"}]}

• I’m trying to figure out how to interact with the Notion MCP since there’s no obvious server or list of servers named Notion. I want to see if calling list_mcp_resources with "notion"
  or other possible server names helps reveal resources, since the user wants me to use Notion MCP to review and optimize their Visual Identity Lab page. It looks like I might need more
  instructions or the user’s help enabling the plugin or confirming the server setup before proceeding.

• Called notion.list_mcp_resources({"server":"notion"})
  └ Error: resources/list failed: unknown MCP server 'notion'

• Called notion_mcp.list_mcp_resources({"server":"notion_mcp"})
  └ Error: resources/list failed: unknown MCP server 'notion_mcp'

─ Worked for 24s ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

• I’m not seeing any Notion MCP resources available from this environment—the server doesn’t appear to be configured—so I can’t browse your workspace yet. Could you confirm that the Notion
  MCP connection is set up on your side (and let me know the server name if it differs)? Once I can reach the pages, I’ll review everything and start improving the Visual Identity Lab page
  as requested.

/mcp

🔌  MCP Tools

  • docker_desktop
    • Status: enabled
    • Auth: Unsupported
    • Command: docker mcp gateway run --tools

Same with 0.50:


╭────────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.50.0)                      │
│                                                │
│ model:     gpt-5-codex high   /model to change │
│ directory: ~/Desktop                           │
╰────────────────────────────────────────────────╯

  To get started, describe a task or try one of these commands:

  /init - create an AGENTS.md file with instructions for Codex
  /status - show current session configuration
  /approvals - choose what Codex can do without approval
  /model - choose what model and reasoning effort to use
  /review - review any changes and find issues


› Using Notion MCP, can you redefine my Visual Identity Lab page to better optimize it and make it clearer. Create a beautiful, engaging, and useful Visual Identity. Before you start, you
    can use the Notion MCP to familiarize yourself with my Notion. Read every page.


• Called codex.list_mcp_resources({})
  └ {"resources": []}

• Called codex.list_mcp_resource_templates({})
  └ {"resourceTemplates": [{"server": "docker_desktop", "name": "Repository Content", "uriTemplate": "repo://{owner}/{repo}/contents{/path*}"}, {"server": "docker_desktop", "name":
        "Repository Content for specific branch", "uriTemplate": "repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}"}, {"server": "docker_desktop", "name": "Repository Content for
        specific pull request", "uriTemplate": "repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}"}, {"server": "docker_desktop", "name": "Repository Content for specific
        tag", "uriTemplate": "repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}"}, {"server": "docker_desktop", "name": "Repository Content for specific commit", "uriTemplate": "repo://
        {owner}/{repo}/sha/{sha}/contents{/path*}"}]}

• It looks like the Notion MCP might not be configured or accessible since I can't find any related resources. I’m considering trying to list resources with a 'notion' server parameter just
  in case, but if that fails, I might need to ask the user to verify the setup before proceeding with reading their Notion pages as requested. This seems critical before I can move forward
  with redefining the Visual Identity Lab page.

• Called notion.list_mcp_resources({"server":"notion"})
  └ Error: resources/list failed: unknown MCP server 'notion'

─ Worked for 25s ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

• I tried listing the available MCP resources, but there’s no Notion MCP server configured in this environment, so I can’t read your Notion pages yet. Could you set up the Notion MCP
  connection (or let me know its server name) so I can review the workspace before drafting the revamped Visual Identity Lab page?
gpeal contributor · 8 months ago

Why don't you try using the Notion MCP directly?

stnwlls · 8 months ago
Why don't you try using the Notion MCP directly?

It's not just Notion, Codex won't recognize any of the tools in Docker automatically.

It successfully searches it's config file first and probes deeper there, which does seem resolved from the last session, so if you'd like to close this, I would say it's resolved. Hopefully in future updates it can search deeper into Docker or other centralized containers that hold MCP servers to know what it can use.