- [How to get better web search in Hermes Agent with the free Parallel MCP](https://parallel.ai/articles/hermes-agent-web-search)
Tags:Guides
November 5, 2026
# How to add free web search to your coding agent in 10 minutes (CLI and MCP)
You can add web search to Claude Code, Cursor, Codex CLI, or OpenClaw for $0 by pointing the agent at Parallel’s keyless MCP server, then add the Parallel CLI and Agent Skills when you want scripting and research. This guide covers the two-minute MCP setup, the eight-minute CLI setup, a test prompt, and fixes for the usual errors.
Tags:Guides
A coding agent that can’t read the web guesses. It writes against a deprecated API, cites a flag that was renamed two releases ago, or misses the migration note that explains your build error. You can give it web search in about 10 minutes without paying anything.
We tested every command below on September 28, 2026 against the live service, with Parallel CLI 0.9.3 and Claude Code 2.1.284, and updated the MCP server names and tool list on November 5, 2026, when Parallel MCP 2.0 launched. The first path takes about two minutes and needs no account. The second takes about eight more, uses the free monthly credits on a Parallel account, and gives the agent a command-line tool it can script.
## The 10-minute checklist
Do Path 1 first; it works on its own. Path 2 is optional and adds capabilities rather than replacing Path 1.
- (0:00) Add the keyless Parallel MCP to your agent with one command or one JSON block.
- (1:30) Restart the session and paste the test prompt from the verify section.
- (2:00) Install the Parallel CLI with pipx or Homebrew.
- (3:30) Run
`parallel-cli login`and approve the device code in your browser. - (5:00) Run your first
`parallel-cli search`and`parallel-cli extract`. - (7:00) Install the Agent Skills with
`parallel-cli skills install`. - (9:00) Ask the agent to use the skill and confirm it runs the CLI.
## Path 1: the keyless Parallel MCP (about 2 minutes, $0)
Parallel MCP[Parallel MCP] is a hosted server at https://mcp.parallel.ai/mcp. It’s free to use anonymously at lower rate limits, with no account and no API key. Without a key it exposes three tools: web_search, which takes an objective plus a few keyword queries and returns ranked URLs with excerpts; web_fetch, which returns markdown from up to 20 URLs; and web_decisions, which answers typed questions (a probability, a pick among options, a score) with sources. Signing in or adding an API key adds web_research, which answers a single research question with citations in the same call. Anonymous calls run in Fast mode, and each call’s excerpts are capped at roughly 25,000 characters so they fit inside typical MCP client output limits.
### Claude Code
Run this in your terminal:
claude mcp add --transport http parallel https://mcp.parallel.ai/mcpStart a new session and run /mcp to confirm the server shows as connected. The /mcp endpoint doesn’t ask for a login. To sign in for web_research and higher limits, add 'https://mcp.parallel.ai/mcp?login' instead (quoted, since ? is special in most shells), then run /mcp, select parallel, and sign in. If you want the config checked into a repo so teammates get it too, add --scope project; Claude Code then writes a .mcp.json file in the project root with "type": "http" and the URL.
### Cursor
Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` for one project:
{
"mcpServers": {
"Parallel": {
"url": "https://mcp.parallel.ai/mcp"
}
}
}### Codex CLI
codex mcp add parallel --url https://mcp.parallel.ai/mcpThe command writes a [mcp_servers.parallel] entry to ~/.codex/config.toml. Restart Codex afterward.
### OpenClaw
openclaw mcp set parallel '{"url":"https://mcp.parallel.ai/mcp","transport":"streamable-http"}'Keep the transport field. OpenClaw treats a server without it as SSE, and Parallel’s MCP server speaks Streamable HTTP, so the connection fails. openclaw mcp set only writes config; start a new agent session for the tools to appear. Our OpenClaw web search best practices[OpenClaw web search best practices] guide covers prompting and accuracy once it’s connected.
Other clients (Windsurf, Gemini CLI, VS Code, Zed, Claude Desktop) use slightly different field names; the installation docs[installation docs] list each one, and parallel.ai/mcp[parallel.ai/mcp] has one-click installs for Claude, ChatGPT, Cursor, VS Code, and others, plus a setup prompt you can paste into any agent. For a wider look at what else is free, see our roundup of the best free web search MCP servers[best free web search MCP servers].
## Verify it works
Paste a prompt that the model can’t answer from training data and that forces a lookup:
12Search the web for the breaking changes in the Next.js 16 upgrade guide. Cite the URLs you used, and quote the minimum Node.js version.```Search the web for the breaking changes in the Next.js 16 upgrade guide.Cite the URLs you used, and quote the minimum Node.js version.```
You should see the agent call `web_search` from the Parallel server with an `objective` and two or three `search_queries`, something like `["Next.js 16 breaking changes", "Next.js 16 upgrade guide"]`. We sent that exact call to the keyless endpoint over raw JSON-RPC with no credentials. It returned 10 results in 0.96 seconds, led by the Next.js 16 release post and the official upgrade guide, and the first excerpt already included the Node.js 20.9 minimum. If the agent answers without a tool call, it’s relying on memory; ask again with “use web_search” in the prompt.
## Path 2: the Parallel CLI and agent skills (about 8 minutes, free credits)
The Parallel CLI[Parallel CLI] gives the agent a shell command instead of a protocol. It needs an account, since it isn’t keyless like the MCP, but every account gets $5 in free credits every month (up to 5,000 Turbo or Fast searches) per the pricing page[pricing page].
### Install and log in
123pipx install "parallel-web-tools[cli]" && pipx ensurepath
# or: brew install parallel-web/tap/parallel-cli
parallel-cli --version``` pipx install "parallel-web-tools[cli]" && pipx ensurepath# or: brew install parallel-web/tap/parallel-cliparallel-cli --version``` Use version 0.9.2 or later. In 0.8.x, `--mode fast` maps to Basic and prints a deprecation warning, so you’d pay the Basic price without getting Fast. Run `pipx upgrade parallel-web-tools` (or `brew upgrade parallel-cli`) if you’re behind. The docs also list npm, uv, and a curl installer, but skill registries flag the `curl | bash` pattern, so prefer pipx or Homebrew if you plan to install skills.
12parallel-cli login parallel-cli auth```parallel-cli loginparallel-cli auth```
`login` runs a device OAuth flow: it opens your browser, you approve, and the CLI stores the credentials. `auth` confirms which credential is active. Setting `PARALLEL_API_KEY` works too, and it overrides the stored login when both exist.
### First search and extract
123456parallel-cli search "Breaking changes in the latest Next.js major release" \
-q "Next.js 16 breaking changes" -q "Next.js upgrade guide" \
--mode fast --json
parallel-cli extract https://nextjs.org/docs/app/guides/upgrading/version-16 \
--objective "List the breaking changes" --json``` parallel-cli search "Breaking changes in the latest Next.js major release" \ -q "Next.js 16 breaking changes" -q "Next.js upgrade guide" \ --mode fast --json parallel-cli extract https://nextjs.org/docs/app/guides/upgrading/version-16 \ --objective "List the breaking changes" --json``` Pass `--mode fast` explicitly. The CLI defaults to Basic, which costs $5 per 1,000 requests; Fast costs $1 per 1,000 and is the mode our search modes docs[search modes docs] recommend starting with. Use `--mode turbo` (about 200ms, English and Japanese queries only) for simple lookups; our sibling guide on Fast vs. Turbo[Fast vs. Turbo] covers that choice in agent loops. On Openbenchmarks’ coding-agent board[coding-agent board] (100 documentation tickets, September 2026), Fast completed 66.7% from search results alone and Turbo 64.7%, a gap inside the run-to-run noise, with Turbo’s searches averaging 333ms.
Because every command takes `--json`, the agent can chain calls in one shell invocation. This pipeline searches, keeps the top three URLs, and extracts all of them:
1234parallel-cli search "Next.js 16 upgrade guide breaking changes" \
--mode fast --max-results 3 --json \
| jq -r '.results[].url' \
| xargs parallel-cli extract --objective "List the breaking changes" --json``` parallel-cli search "Next.js 16 upgrade guide breaking changes" \ --mode fast --max-results 3 --json \ | jq -r '.results[].url' \ | xargs parallel-cli extract --objective "List the breaking changes" --json``` ### Install the skills
12parallel-cli skills install # global: ~/.agents/skills (+ .claude/skills if Claude Code is present)
parallel-cli skills install --project # this repo only``` parallel-cli skills install # global: ~/.agents/skills (+ .claude/skills if Claude Code is present)parallel-cli skills install --project # this repo only``` In our test repo, `--project` installed 14 skills into `.agents/skills` and `.claude/skills`, including `parallel-web-search`, `parallel-web-extract`, `parallel-deep-research`, `parallel-data-enrichment`, and `parallel-findall`. Each skill is a `SKILL.md` file that teaches the agent the right CLI invocation. To verify, ask the agent to “use the parallel-web-search skill” on the Next.js prompt above; you should see it run `parallel-cli search ... --json` through its shell tool. The search skill’s default command doesn’t set a mode, so those calls run in Basic unless you tell the agent to add `--mode fast`.
## When to prefer the CLI over the MCP
Use the MCP when you want zero setup and the agent needs search, fetch, or (once you sign in) quick answers to single research questions. Move to the CLI when the agent needs to script, save results, or reach beyond search.
Context cost is the argument you’ll hear first. Parallel MCP’s default tools/list response is more than 20,000 characters of schema, and in clients that load MCP schemas up front, that sits in context every turn; adding ?tools=web_search,web_fetch to the URL trims it to about 14,600. A skill loads only its short description until the agent invokes it; the parallel-web-search description is about 400 characters. The gap is smaller in Claude Code than it used to be, since Claude Code now defers MCP tool schemas by default[defers MCP tool schemas by default] through tool search. Our MCP vs. skills vs. CLIs[MCP vs. skills vs. CLIs] decision framework covers where each mechanism wins, including where MCP’s typed schemas and per-tool approvals help.
The stronger reasons are practical. The CLI composes with pipes, jq, and scripts, so one bash call does what would take several MCP round trips. --json output and stdin input (parallel-cli search -) make it safe to run non-interactively in CI. You can pick any search mode per command, where anonymous MCP calls always run Fast and signed-in connections set a mode through the x-parallel-mcp-config header. The CLI also reaches the rest of the platform: research run for deep research, enrich for adding web-sourced columns to a CSV, findall for building entity lists, and monitor for recurring checks. If you want to wrap other tools the same way, turn any CLI into an agent skill[turn any CLI into an agent skill] walks through the pattern.
| Parallel MCP (keyless) | Parallel CLI + skills | |
|---|---|---|
| Setup time | About 2 minutes | About 8 minutes |
| Account needed | No | Yes (login or API key) |
| Cost | $0 anonymous; paid per request with sign-in or a key | $5 free credits per month, then per request |
| Search modes | Fast when anonymous; any mode via a config header with sign-in or a key | Turbo, Fast, Basic, Advanced |
| Other APIs | Search, fetch, and decisions; research with sign-in or a key | Extract, research, enrich, FindAll, Monitor |
| Best for | Interactive coding sessions, quick lookups | Scripts, CI, piping, research tasks |
You can run both: keep the MCP for everyday lookups and let the agent reach for the CLI skill when it needs deep research or saved JSON.
## Troubleshooting
OpenClaw connects but no tools appear. Check that the config includes "transport": "streamable-http", since OpenClaw defaults to SSE, and start a new session. openclaw mcp show parallel prints the saved definition.
Searches get rate limited. Anonymous access runs at lower rate limits, and we don’t publish a fixed number for it; calls past the limit are rate limited, not billed. Sign in through https://mcp.parallel.ai/mcp?login in clients that support MCP OAuth (Claude Code, Codex, Cursor), or create a key at platform.parallel.ai[platform.parallel.ai] and send it as a Bearer token. In Claude Code, add --header "Authorization: Bearer $PARALLEL_API_KEY" to the claude mcp add command; in Codex, add --bearer-token-env-var PARALLEL_API_KEY. Authenticated calls count against your credits, and a 402 error means the balance is empty.
**`parallel-cli: command not found`.** pipx installed it outside your PATH. Run `pipx ensurepath` and open a new terminal.
**Login on a server or in a container.** Run `parallel-cli login --no-browser`, open the printed URL on any device, and enter the code. For CI, set `PARALLEL_API_KEY` instead. Older docs mention `login --device`; neither 0.8.2 nor 0.9.3 accepts that flag, because `login` already uses the device flow.
**The CLI warns that `--mode fast` is deprecated.** You’re on 0.8.x. Upgrade to 0.9.2 or later.
## Get started
Add the free Parallel MCP[free Parallel MCP] now; it takes one command. When you want scripting and research, create an account at platform.parallel.ai[platform.parallel.ai], install the Parallel CLI[Parallel CLI], and run parallel-cli skills install. For picking other servers to pair with it, see the best MCP servers for Claude Code[best MCP servers for Claude Code].
## Frequently asked questions
### How do I add web search to Claude Code?
Run claude mcp add --transport http parallel https://mcp.parallel.ai/mcp, then start a new session. The server is free and needs no API key.
### Is there a free web search API for coding agents?
Yes. Parallel MCP[Parallel MCP] is free to use anonymously at lower rate limits, and a Parallel account adds $5 in free credits every month, which covers up to 5,000 Turbo or Fast searches through the API or CLI.
### Does Claude Code already have web search?
Yes, Claude Code has a built-in web search tool. A dedicated search server adds dense excerpts and a separate fetch tool; our comparison of Claude’s built-in search with Parallel[comparison of Claude’s built-in search with Parallel] covers the differences.
### Should I use an MCP server or a CLI for web search?
Use the MCP for the fastest setup and interactive sessions. Use the CLI with skills when the agent needs to pipe results, run in CI, or call deep research, enrichment, or FindAll.
### Do I need an API key for the Parallel CLI?
Yes. The CLI needs either parallel-cli login or a PARALLEL_API_KEY. Only the hosted Parallel MCP works without one.
**Related reading: **Best free web search MCP servers[Best free web search MCP servers] / Fast vs. Turbo: choosing a Parallel Search mode[Fast vs. Turbo: choosing a Parallel Search mode] / What is a CLI, and why do AI agents like using them?[What is a CLI, and why do AI agents like using them?] / MCP servers vs. agent skills vs. CLIs[MCP servers vs. agent skills vs. CLIs]