OpenAI Codex

Codex is OpenAI’s coding agent. It can reach the Datamesh MCP server either way — a remote streamable-HTTP endpoint or a local stdio server — configured in ~/.codex/config.toml (or a per-project .codex/config.toml in a trusted project). Codex chooses the transport from the keys present: url for HTTP, command for stdio.

One config for the CLI and the desktop app

The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share the same MCP configuration on a machine: per OpenAI’s MCP documentation, “The ChatGPT desktop app, Codex CLI, and IDE extension share this configuration.” A server you add to ~/.codex/config.toml therefore appears in all three, and servers added in the desktop app (Settings → MCP servers → Add server, then Restart) are shared with the CLI. Restart the desktop app to pick up changes made to the file by hand.

Each [mcp_servers.<name>] table needs a unique name. The examples below use oceanum-datamesh-hosted and oceanum-datamesh-local, so you can configure either or both. Defining the same table twice is invalid TOML and breaks the whole config file, so don’t rename both to the same name.

Hosted server (http)

Add a streamable-HTTP server with the Datamesh endpoint and an X-DATAMESH-TOKEN header. To keep the token out of the file, read the header value from an environment variable with env_http_headers, which maps each header name to the name of an environment variable (not its value). The complete entry for ~/.codex/config.toml is:

[mcp_servers.oceanum-datamesh-hosted]
url = "https://mcp.oceanum.io/datamesh"
tool_timeout_sec = 300

[mcp_servers.oceanum-datamesh-hosted.env_http_headers]
X-DATAMESH-TOKEN = "DATAMESH_TOKEN"

Codex reads DATAMESH_TOKEN from its own process environment when it starts, so the variable must be exported in the environment Codex is launched from:

• CLI — export it in the shell, then start Codex from that shell:

  export DATAMESH_TOKEN="your-datamesh-token"
  codex

  Add the export line to your shell profile (for example ~/.zshrc or ~/.bashrc) to make it permanent.

• Desktop app — the reliable option is the static http_headers form below, which doesn’t depend on the app’s environment. If you want to keep using the environment variable, the following OS-level steps should work if the app inherits your user environment; they aren’t covered by the Codex documentation.

• Desktop app on macOS (OS-level) — apps started from the Dock or Finder don’t read your shell profile. Set the variable for GUI apps, then quit and reopen the app:

  launchctl setenv DATAMESH_TOKEN "your-datamesh-token"

  This lasts until you log out or restart, so repeat it after a reboot (or use the static header below).

• Desktop app on Windows (OS-level) — set a user environment variable, then quit and reopen the app:

  setx DATAMESH_TOKEN "your-datamesh-token"

If the variable is unset or blank where Codex runs, Codex doesn’t send the header at all, so the server rejects the request as unauthenticated (see Troubleshooting).

Static header

To store the token in the file instead — the recommended form for the desktop app — use an http_headers table, which maps header names to static values, in place of env_http_headers:

[mcp_servers.oceanum-datamesh-hosted]
url = "https://mcp.oceanum.io/datamesh"
tool_timeout_sec = 300

[mcp_servers.oceanum-datamesh-hosted.http_headers]
X-DATAMESH-TOKEN = "your-datamesh-token"

tool_timeout_sec raises the time Codex waits for a single tool call from its default of 60 seconds, which large query_data or export_query requests can exceed.

The hosted server is read-only and returns query_data results inline (up to ~50 MB). For larger results, Codex can call export_query, which on the hosted server returns a time-limited download link to the full result — the link needs no token, so treat it like a password. The local server below writes export_query output to a file instead.

Note: some Codex releases have had rough edges with streamable-HTTP MCP servers. If the connection misbehaves, use the local stdio server below — it is the most reliable transport for a CLI agent.

Local server (stdio)

For full read/write, and to have export_query write results straight to a file on your machine, run the server locally. The complete entry for ~/.codex/config.toml is:

[mcp_servers.oceanum-datamesh-local]
command = "uvx"
args = ["--python", "3.13", "oceanum-mcp", "datamesh"]
startup_timeout_sec = 120
tool_timeout_sec = 300

[mcp_servers.oceanum-datamesh-local.env]
DATAMESH_TOKEN = "your-token-here"

Replace your-token-here with your Datamesh token. To keep the token out of the file, remove the env table and forward DATAMESH_TOKEN from Codex’s environment instead — the variable must then be exported where Codex is launched from, exactly as for the hosted server:

[mcp_servers.oceanum-datamesh-local]
command = "uvx"
args = ["--python", "3.13", "oceanum-mcp", "datamesh"]
env_vars = ["DATAMESH_TOKEN"]
startup_timeout_sec = 120
tool_timeout_sec = 300

Or add the server from the command line, then add the timeouts to the generated [mcp_servers.oceanum-datamesh-local] table in config.toml:

codex mcp add oceanum-datamesh-local --env DATAMESH_TOKEN=your-token-here -- uvx --python 3.13 oceanum-mcp datamesh

This requires uv on your PATH. The --python 3.13 argument has uv run the server on Python 3.13 (downloading it if needed), as some of the server’s dependencies don’t yet install on Python 3.14. List configured servers with codex mcp list.

Timeouts

Codex gives an MCP server 10 seconds to start (startup_timeout_sec) and 60 seconds per tool call (tool_timeout_sec) by default. The first uvx launch downloads Python 3.13 and the server’s dependencies, which can take well over 10 seconds, so Codex reports the server as failed to start even though it would have come up. Setting startup_timeout_sec = 120 covers the first run; later starts use the uv cache and are much faster. Raise tool_timeout_sec if large exports time out.

Troubleshooting

Codex often reports an authentication failure from the hosted server as a connection or network error, so check the token first.

Symptom	Likely cause	Fix
Hosted server fails to connect, or shows a network/connection error	Token missing, mistyped, revoked or expired	Check the token on your Datamesh token page and update the config or environment variable
Hosted server fails to connect with env_http_headers, but works with http_headers	DATAMESH_TOKEN isn’t exported in the environment Codex was launched from (common with the desktop app)	Export it where Codex starts (see Hosted server) and restart Codex
Hosted server fails to connect even though the token is correct	Wrong header name	The header must be X-DATAMESH-TOKEN; in env_http_headers the value is the variable name, not the token
Local server “failed to start” or timed out, especially on first use	uvx cold start exceeds the 10-second default	Set startup_timeout_sec = 120; run uvx --python 3.13 oceanum-mcp datamesh once in a terminal to warm the cache
Local server fails to start with command not found	uv isn’t on the PATH Codex sees	Install uv and restart Codex (and your shell)
A datasource you expect is missing from search results, or reported as not found	Your token’s organisation isn’t entitled to that datasource	Check access with your Oceanum administrator, or use a token from the organisation that has access
Large queries or exports time out	Tool call exceeds the 60-second default	Raise tool_timeout_sec, or narrow the query
Config stops loading after adding a server	Two [mcp_servers.<name>] tables share a name	Give each server a unique name

Keep your token safe

Your Datamesh token grants access to all of your organisation’s permissioned datasources — including the ability to modify or delete them. Treat it as a secret, and prefer the hosted read-only server for exploratory use.