# How do I add UpRock to OpenAI's Codex CLI? Run codex mcp add uprock --url https://mcp.uprock.ai/mcp --bearer-token-env-var UPROCK_API_KEY, and Codex can load pages on an opted-in device in the country you choose for $0.50 per 1,000 pages, with the key kept in your environment instead of config.toml. Raise tool_timeout_sec above Codex's 60-second default. Updated 29 Oct 2026. Web page: https://uprock.ai/integrations/codex ## On this page - [What Codex gets](#what-codex-gets) - [Set it up](#set-it-up) - [Check it works](#check-it-works) - [Tell Codex when to use it](#tell-codex-when-to-use-it) - [A working call](#a-working-call) - [Limits worth knowing](#limits-worth-knowing) - [FAQ](#faq) - [Other use cases to explore](#explore) - [Related articles](#related) - [References](#references) - [Get started](#get-started) ## 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: | Tool | What it does | Does Codex ask first? | |---|---|---| | `crawl_fetch` | Loads a page in a real browser on a desktop or mobile device in the country you pass; returns a summary and links to the stored markdown and HTML | No, it's marked read-only | | `resource_fetch` | Reads a stored result in full, such as that markdown | No, it's marked read-only | | `verify` | Loads one URL from several regions with status, timings and screenshots | No, it's marked read-only | | `video_search` | Finds moments in public video by meaning | No, it's marked read-only | | `video_moment` | Reads the time-stamped moments of one video | Yes. Use with care: it returned 502 "temporarily unavailable" when we tested on 25 Oct 2026 | | `web_research` | Searches several engines from chosen countries | No, so the config below switches it off. Use with care: on 25 Oct 2026, 4 of the 8 results for a query about the MCP spec were unrelated Wikipedia pages | ## 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: ```bash 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: ```toml [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 s disabled_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: ```toml [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 ```toml [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 ```bash codex mcp list codex mcp get uprock ``` With option 1, this is what Codex 0.165.0 printed on 29 Oct 2026: ```text Name Url Bearer Token Env Var Status Auth uprock https://mcp.uprock.ai/mcp UPROCK_API_KEY enabled Bearer token uprock 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: ```markdown ## 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: ```bash 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: ```json { "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. ## FAQ ### Can I keep the API key out of config.toml? Yes. Set bearer_token_env_var = "UPROCK_API_KEY" in the uprock table and Codex sends the key in an Authorization header, read from your environment when the server starts. UpRock has accepted the key that way since 28 Oct 2026. After a test run set up like this we found no copy of the key anywhere in Codex's home folder. ### Does Codex ask before every UpRock call? No. With Codex's default approval mode, tools that declare themselves read-only run without a prompt, and UpRock marks crawl_fetch, resource_fetch, verify, video_search and web_research that way. Set approval_mode = "prompt" on a tool to be asked each time. ### Why did a fetch fail after a minute? Codex gives an MCP tool 60 seconds by default. A fresh UpRock fetch usually takes 10 to 40 seconds but can run longer while it retries on a fresh device, so set tool_timeout_sec = 300 in the uprock table. ### Do I need codex mcp login? No. UpRock doesn't use OAuth; your API key is the login. ### What does a crawl_fetch call cost? One credit per page fetched, which is $0.50 per 1,000 pages by card or USDC and $0.40 with UPT, prepaid. Video search is $1 per 1,000 searches. ## Other use cases to explore - [Check a deploy from several regions](https://uprock.ai/use-cases/check-a-site-from-many-regions): load one URL from North America, Europe and Asia at once and compare load times. - [Retry a page your agent got a 403 on](https://uprock.ai/use-cases/agent-gets-403): which failures are worth a second network and which to leave alone. - [See a page as it looks in another country](https://uprock.ai/use-cases/page-from-another-country): one store page from five countries, with five prices, two languages and a cookie banner in one country only. - [Search public video by moment](https://uprock.ai/video-semantic-search): find the second something is shown or said, across platforms. ## Related articles - [How do I give Claude Code live web access with UpRock?](https://uprock.ai/integrations/claude-code.md): Add UpRock's MCP server to Claude Code with the key kept out of your repo, check it's connected, tell Claude when to use it, and know the output limits that matter for big pages. - [How do I add UpRock to Cursor?](https://uprock.ai/integrations/cursor.md): Add UpRock's MCP server to Cursor with the key read from your environment, turn it on, pre-approve the fetch tools, add a rule for when to use it, and run it from Cursor's command-line agent. - [How do I use UpRock as a LangChain tool?](https://uprock.ai/integrations/langchain.md): Load UpRock's MCP tools into LangChain in Python or JavaScript, call them directly or from an agent, and handle the result format, with code we ran against the live server. - [How do I give a Vercel AI SDK app web access with UpRock?](https://uprock.ai/integrations/vercel-ai-sdk.md): Connect UpRock's MCP server with @ai-sdk/mcp, call its tools directly or let the model choose them in generateText, and avoid the timeout and key-logging traps, with code we ran against the live server. - [How do I fetch web pages from a chosen country in n8n?](https://uprock.ai/integrations/n8n.md): Install UpRock's verified n8n node, add your key, import a two-node workflow we ran in n8n 2.44, and read the page's markdown in the next step, or give the node to an AI Agent as a tool. - [How do I give a CrewAI agent web access with UpRock?](https://uprock.ai/integrations/crewai.md): Load UpRock's MCP tools into CrewAI with MCPServerAdapter and the key in a header, why it beats the mcps field's 30-second limit, and how to read what the tools return, with tested code. - [How do I give a Mastra agent web access with UpRock?](https://uprock.ai/integrations/mastra.md): Connect UpRock's MCP server with MCPClient from @mastra/mcp, raise its 60-second timeout, and call the tools directly or from an Agent, with tested code. - [Integrations: all articles](https://uprock.ai/integrations.md) ## References 1. [OpenAI, Codex docs, Model Context Protocol (CLI setup and config.toml options)](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), checked 25 Oct 2026 2. [OpenAI, Codex docs, Configuration reference (mcp_servers keys and defaults)](https://learn.chatgpt.com/docs/config-file/config-reference), checked 25 Oct 2026 3. [OpenAI, Codex docs, Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md), checked 25 Oct 2026 4. [OpenAI, Codex docs, Non-interactive mode (codex exec)](https://learn.chatgpt.com/docs/non-interactive-mode), checked 25 Oct 2026 5. [OpenAI, Codex source, MCP tool approval rules (mcp_tool_call.rs)](https://github.com/openai/codex/blob/main/codex-rs/core/src/mcp_tool_call.rs), checked 25 Oct 2026 6. [@openai/codex on npm](https://www.npmjs.com/package/@openai/codex), checked 29 Oct 2026 7. [UpRock, setup for every agent](https://uprock.ai/agents.md), checked 25 Oct 2026 8. [UpRock, everything in one file (API, CLI, MCP, pricing)](https://uprock.ai/llms-full.txt), checked 25 Oct 2026 ## Get started Get an API key: https://uprock.ai/app/api-keys Paste this into your agent: ```text Set up UpRock for me: read https://uprock.ai/agents.md, connect the UpRock MCP server, and run one test crawl. Tell me what it costs before you spend anything. ``` Setup for every client (MCP, skill, CLI): https://uprock.ai/agents.md