# How do I give Claude Code live web access with UpRock?

Add UpRock's MCP server to Claude Code with a .mcp.json file that sends your key in a header, read from the UPROCK_API_KEY environment variable, so the key never lands in a file you commit. Or install the UpRock plugin, which keeps the key in your OS keychain. Claude Code then gets crawl_fetch, which loads a page on an opted-in device in the country you choose for $0.50 per 1,000 pages, plus video search.

Updated 29 Oct 2026. Web page: https://uprock.ai/integrations/claude-code

## On this page

- [What Claude Code gets](#what-claude-code-gets)
- [Set it up](#set-it-up)
- [Check it works](#check-it-works)
- [Tell Claude when to use it](#tell-claude-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 Claude Code gets

UpRock's MCP server runs over streamable HTTP at `https://mcp.uprock.ai/mcp`, with your API key in an `Authorization: Bearer` header. Once it's added as `uprock`, Claude Code sees these tools, named `mcp__uprock__<tool>`:

| Tool in Claude Code | What it does | When Claude should use it |
|---|---|---|
| `mcp__uprock__crawl_fetch` | Loads a page in a real browser on a desktop or mobile device in the country you pass, and returns a summary plus links to the stored markdown and HTML | A page from a specific country, or a fetch that failed elsewhere |
| `mcp__uprock__resource_fetch` | Reads a stored result in full, such as the markdown of a page crawl_fetch loaded | Right after crawl_fetch, when the summary isn't enough |
| `mcp__uprock__video_search` | Finds moments in public video by meaning, with the video link and the start and end times | When the answer is in a video |
| `mcp__uprock__video_moment` | Describes what happens in a stretch of one video | After video_search, on the best hit |
| `mcp__uprock__sweep` | Loads one URL from several regions and reports status, timings and screenshots | Checking a site from around the world |
| `mcp__uprock__web_research` | Searches several engines from the countries you pick | Use with care: when we tested on 21 Oct 2026 it returned empty or off-topic results from some countries |

## Set it up

### Option 1: a project .mcp.json, with the key in your environment (recommended)

Put this in `.mcp.json` at the root of your project. It's safe to commit: the key stays in your environment.

```json
{
  "mcpServers": {
    "uprock": {
      "type": "http",
      "url": "https://mcp.uprock.ai/mcp",
      "headers": { "Authorization": "Bearer ${UPROCK_API_KEY}" }
    }
  }
}
```

Then set the key in your shell profile (get one at uprock.ai/app/api-keys) and open a new terminal:

```bash
export UPROCK_API_KEY=your-key   # in ~/.zshrc or ~/.bashrc
```

Claude Code fills in `${UPROCK_API_KEY}` on every request. If the variable isn't set, `claude mcp list` shows a config warning and the server still connects, but every tool call comes back with "An UpRock API key is required".

### Option 2: one command, for just you

```bash
claude mcp add --transport http uprock https://mcp.uprock.ai/mcp --header "Authorization: Bearer $UPROCK_API_KEY"
```

This adds the server for the current project only (the default "local" scope, stored in `~/.claude.json`), with your key stored as text in that file. Add `--scope user` to make it available in every project. `claude mcp list` doesn't show the key, but `claude mcp get uprock` prints it.

### Option 3: the UpRock plugin

The [UpRock plugin](https://github.com/uprockcom/uprock-claude-plugin) bundles the MCP server with a few slash commands. Add its marketplace and install it:

```bash
claude plugin marketplace add uprockcom/uprock-claude-plugin
claude plugin install uprock@uprock
```

Inside a session, `/plugin marketplace add` and `/plugin install` do the same. Claude Code then asks for your UpRock API key and keeps it in your OS keychain; `/uprock:setup` checks the connection. If you allow tools in `.claude/settings.json` as shown below, check the plugin's tool names in `/mcp` first.

### Option 4: add the skill

The UpRock skill teaches Claude when to reach for UpRock and what it costs. Download it from uprock.ai/skill/uprock-skill.zip and unzip it into `~/.claude/skills/`, so you end up with `~/.claude/skills/uprock/SKILL.md`. Use it together with option 1 or 2.

## Check it works

```bash
claude mcp list
```

With option 1, the first run in a project shows the server waiting for approval:

```text
uprock: https://mcp.uprock.ai/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)
```

Start `claude` in that folder and approve the server. This is what the list showed after that on 29 Oct 2026:

```text
uprock: https://mcp.uprock.ai/mcp (HTTP) - ✔ Connected
```

Inside a session, `/mcp` lists the server and its tool count.

## Tell Claude when to use it

Claude chooses tools by reading their descriptions, and a line in `CLAUDE.md` makes the choice predictable:

```text
Web pages: use your normal fetch first. If it fails or returns 401/403/429, or I ask for a page
as it looks in a specific country, use UpRock's crawl_fetch with that country, then
resource_fetch on the markdown resource for the full text. Ask before fetching more than 100 pages.
```

To stop Claude asking for permission on every call, allow the two fetch tools in `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": ["mcp__uprock__crawl_fetch", "mcp__uprock__resource_fetch"]
  }
}
```

## A working call

From a terminal, in the project with the `.mcp.json` above:

```bash
claude -p "Use the uprock crawl_fetch tool to load https://example.com from Germany (country DE) and tell me the page title." \
  --allowedTools "mcp__uprock__crawl_fetch"
```

Claude calls `crawl_fetch` with `{"url": "https://example.com", "country": "DE"}`. This is the start of what the tool returned when we made that call on 21 Oct 2026 (resource IDs shortened):

```json
{
  "status": "success",
  "meta": { "url": "https://example.com", "title": "Example Domain", "content_type": "text/html", "time_ms": 1316 },
  "content": {
    "markdown": { "resource": "crawl://…/markdown", "size_bytes": 1342, "mime_type": "text/markdown" },
    "html": { "resource": "crawl://…/html", "size_bytes": 2358, "mime_type": "text/html" }
  }
}
```

The summary is small on purpose. When Claude needs the whole page, it calls `resource_fetch` with the markdown resource.

## Limits worth knowing

- **Output size.** Claude Code warns when a tool returns more than 10,000 tokens and cuts output at 25,000 by default. `resource_fetch` on a long page can pass that; raise it with `MAX_MCP_OUTPUT_TOKENS`. Text results over 50,000 characters are saved to a file instead.
- **Time.** A fresh fetch takes 10 to 40 seconds, and a recently fetched page about a second. Claude Code moves calls that run past two minutes to the background in interactive sessions.
- **Where the key ends up.** With option 1 it stays in your environment. With option 2 it's stored as text in `~/.claude.json`, and `claude mcp get uprock` prints it, so keep that output out of issues and screenshots. The plugin keeps it in your OS keychain.

On 29 Oct 2026, with Claude Code 2.1.312, both option 1 and option 2 showed `✔ Connected` to the live server; pointed at a local test server, option 1 sent the header with the variable filled in. We installed the plugin with the two commands above, and made `crawl_fetch` calls against the live server with the key in the header. Earlier, on 21 Oct, we made the same `crawl_fetch` and `resource_fetch` calls with the key in the URL through the official MCP SDK. Our test environment couldn't run a full Claude session, so the `claude -p` step follows Claude Code's docs.

## FAQ

### Can I keep the API key out of .mcp.json?

Yes. Claude Code expands environment variables in .mcp.json, headers included, so "Authorization": "Bearer ${UPROCK_API_KEY}" works and the file is safe to commit. UpRock has accepted the key in that header since 28 Oct 2026.

### Plugin or MCP server?

The plugin is the quickest start: it adds the same MCP server, asks for your key once and keeps it in your OS keychain, and adds slash commands such as /uprock:setup. A .mcp.json in your repository lets a whole team share the setup, with each person's key in their own environment.

### Why does claude mcp list say Pending approval?

Servers defined in a project's .mcp.json need your approval the first time. Start claude in that folder and approve the server; after that the list shows it as connected. One-shot claude -p runs load project servers without asking.

### 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 credits, no plan.

### A big page came back cut off. Why?

Claude Code limits MCP tool output to 25,000 tokens by default and warns above 10,000. crawl_fetch itself returns a short summary, but resource_fetch on a long page can pass the limit. Raise it with the MAX_MCP_OUTPUT_TOKENS environment variable.

### Do I need the UpRock skill as well as the MCP server?

No, but it helps. The skill is a short SKILL.md that tells Claude when UpRock is the right tool (a blocked fetch, a page from one country, an answer inside a video) and what it costs. The MCP server is what actually runs the calls.

## Other use cases to explore

- [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.
- [Decide which failed pages are worth retrying](https://uprock.ai/use-cases/agent-gets-403): a diagnosis table from status code to the legitimate fix, and when to stop.
- [Use UpRock next to another crawler in Claude Code](https://uprock.ai/compare/firecrawl#if-youd-rather-not-write-code): keep Firecrawl first and tell Claude when to switch, in three lines of CLAUDE.md.
- [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 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 add UpRock to OpenAI's Codex CLI?](https://uprock.ai/integrations/codex.md): Add UpRock's MCP server to Codex with one command, keep the API key in an environment variable, raise the 60-second tool timeout, and add your own rules in AGENTS.md.
- [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. [Claude Code docs, Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp), checked 21 Oct 2026
2. [Claude Code docs, Permissions (allowing MCP tools)](https://code.claude.com/docs/en/permissions), checked 21 Oct 2026
3. [Claude Code docs, Memory (CLAUDE.md and AGENTS.md)](https://code.claude.com/docs/en/memory), checked 21 Oct 2026
4. [Claude Code docs, Skills](https://code.claude.com/docs/en/skills), checked 21 Oct 2026
5. [Claude Code docs, Headless mode (claude -p)](https://code.claude.com/docs/en/headless), checked 21 Oct 2026
6. [UpRock plugin for Claude Code (uprockcom/uprock-claude-plugin)](https://github.com/uprockcom/uprock-claude-plugin), checked 29 Oct 2026
7. [Claude Code docs, Install and manage plugins](https://code.claude.com/docs/en/discover-plugins), checked 29 Oct 2026
8. [UpRock, setup for every agent](https://uprock.ai/agents.md), checked 21 Oct 2026
9. [UpRock, the agent skill](https://uprock.ai/skill/SKILL.md), checked 21 Oct 2026
10. [UpRock, everything in one file (API, CLI, MCP, pricing)](https://uprock.ai/llms-full.txt), checked 21 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