How do I add UpRock to OpenAI's Codex CLI?

What Codex gets

UpRock's MCP server runs over streamable HTTP at https://mcp.uprock.ai/mcp, with your API key in an Authorization: Bearer header. Added as uprock, it gives Codex six tools. Codex's default approval mode skips the prompt for tools that declare themselves read-only, so the last column says what happens when the model calls each one:

Set it up

Get a key at uprock.ai/app/api-keys. Codex keeps MCP servers in ~/.codex/config.toml, which the CLI, the IDE extension and the ChatGPT desktop app share.

Option 1: the key in your environment

Put export UPROCK_API_KEY=your-key in ~/.zshrc or ~/.bashrc, then:

codex mcp add uprock --url https://mcp.uprock.ai/mcp --bearer-token-env-var UPROCK_API_KEY

Codex writes a table with no key in it. Open ~/.codex/config.toml and add two lines under it:

[mcp_servers.uprock]url = "https://mcp.uprock.ai/mcp"bearer_token_env_var = "UPROCK_API_KEY"tool_timeout_sec = 300             # Codex's default is 60; a fresh fetch can take 10 to 40 sdisabled_tools = ["web_research"]  # off-topic results in our tests; Codex has its own web search

To be asked before each fetch (each one uses a credit), add a per-tool override:

[mcp_servers.uprock.tools.crawl_fetch]approval_mode = "prompt"

With no key in it, this table can go in a project's .codex/config.toml and be committed (Codex reads project config only in trusted projects).

Codex reads the variable when the server starts. If it isn't set, Codex stops with Environment variable UPROCK_API_KEY for MCP server 'uprock' is not set. An app started from the Dock or Start menu may not see what your shell profile exports; use option 2 there.

Option 2: the key in the config file

[mcp_servers.uprock]url = "https://mcp.uprock.ai/mcp"http_headers = { "Authorization" = "Bearer your-key" }

Put your key in place of your-key in ~/.codex/config.toml, and add tool_timeout_sec and disabled_tools as in option 1. Codex sends the header on every call, and this works anywhere Codex reads that file, but keep the file out of Git because it holds the key.

Check it works

codex mcp listcodex mcp get uprock

With option 1, this is what Codex 0.165.0 printed on 29 Oct 2026:

Name    Url                        Bearer Token Env Var  Status   Authuprock  https://mcp.uprock.ai/mcp  UPROCK_API_KEY        enabled  Bearer tokenuprock  enabled: true  disabled_tools: web_research  transport: streamable_http  url: https://mcp.uprock.ai/mcp  bearer_token_env_var: UPROCK_API_KEY  http_headers: -  env_http_headers: -  http_headers_helper: -  tool_timeout_sec: 300  remove: codex mcp remove uprock

Inside a session, /mcp lists the server and its tools.

Tell Codex when to use it

Codex reads the instructions an MCP server sends when it connects. UpRock's say to use it as a second provider, when other fetch or search tools are blocked, rate-limited or return bot-check pages, or when a page is needed as someone in a specific country or on a specific device sees it (checked 29 Oct 2026). For rules of your own, such as a page limit, use AGENTS.md, either ~/.codex/AGENTS.md for every project or AGENTS.md at the repository root:

## Web pages- Use your normal web access first. If a page fails or returns 401, 403 or 429, or I ask  for a page as it looks in a specific country, call the uprock MCP tool crawl_fetch with  the url and country, then resource_fetch on the markdown resource it returns.- Ask before fetching more than 100 pages in one task.

Codex reads these files once per run, so start a new session after editing.

A working call

From a terminal inside a Git repository (codex exec won't run elsewhere without --skip-git-repo-check), with option 1 or 2 in place:

codex exec "Use the uprock crawl_fetch tool to load https://example.com from Germany (country DE) and tell me the page title."

Codex calls crawl_fetch with {"url": "https://example.com", "country": "DE"}. This is the start of what came back when Codex made that call through its own MCP client on 25 Oct 2026 (resource IDs and content URLs shortened); the same call with option 1 returned the same shape on 29 Oct:

{  "status": "success",  "meta": { "url": "https://example.com", "title": "Example Domain", "content_type": "text/html", "status_code": 200, "time_ms": 1480 },  "summary": "This web page explains that the domain `example.com` is reserved for use in documentation examples ...",  "content": {    "markdown": { "resource": "crawl://…/markdown", "size_bytes": 1342, "mime_type": "text/markdown" },    "html": { "resource": "crawl://…/html", "size_bytes": 2358, "mime_type": "text/html" }  }}

For the whole page, Codex follows up with resource_fetch on the markdown resource. In scripts, add --json to codex exec and the MCP tool calls appear as items in the JSON Lines stream.

Limits worth knowing

• Time. crawl_fetch starts up to two more attempts on fresh devices, 7 seconds apart, keeps the first that succeeds, and has its own 60-second timeout by default. Codex also gives a tool 60 seconds by default, so a slow fetch can be cut off just before it finishes; tool_timeout_sec = 300 avoids that. Through Codex, a fresh fetch took 10 seconds and a recently fetched page under half a second in our tests.
• Long pages. Codex trims long tool output to a budget that depends on the model. If resource_fetch comes back cut short, set tools.resource_fetch.output_token_limit in the uprock table.
• codex exec and approvals. A tool that needs approval is refused when the approval policy is never. Here that only affects video_moment; give it approval_mode = "approve" if you need it in scripts.
• Keep the key out of the URL. Codex can write a server's full URL into its local log database (logs_2.sqlite in your Codex home) when it checks the server for OAuth; with the key in the URL, we found it there after a test run on 25 Oct. With the key in a header there's none in the URL, and on 29 Oct we found none in Codex's home after an option 1 run.
• Don't build on meta.status_code. When we fetched a page that answers 403, status said success and meta.status_code was missing.

On 29 Oct 2026, with Codex 0.165.0 from npm, codex mcp add --bearer-token-env-var wrote the option 1 table, and Codex's own MCP client, driven through codex app-server, called crawl_fetch on the live server with the key read from UPROCK_API_KEY; with the variable unset it stopped with the error above. Earlier, on 25 Oct 2026 with Codex 0.164.0, codex mcp add with a dummy key wrote a table holding the URL (option 2), and pointed at a local test server, Codex sent ${VAR} in url as literal text, which is why the key can't be put in the URL from an environment variable. codex debug prompt-input showed the AGENTS.md text in the model's instructions. Codex's own MCP client, driven through codex app-server, listed five tools (web_research switched off) and called crawl_fetch and resource_fetch on the live UpRock server; we made the same calls through the official MCP SDK. We couldn't run a model turn without an OpenAI account: codex exec got as far as the model request and stopped at sign-in, so the rest of that step and the approval behaviour follow Codex's docs and source.