Add Parallel Search MCP to an Existing Agent: Keyless Search, Page Fetching, and Cost Boundaries

You can add it without operating a search service or obtaining a search API key. Parallel exposes a hosted Streamable HTTP endpoint at https://search.parallel.ai/mcp and gives an agent two tools: web_search and web_fetch. The reliable workflow is not “save the config and assume it works.” Verify the connection, confirm both tools are discoverable, inspect the actual tool-call events, and open the source URLs returned by the tools.

“Keyless search” does not make the entire agent workflow free. Anonymous Search MCP access, an authenticated Parallel account, the Claude Code/Codex client, and the model API are separate boundaries. The steps below are based on official pages opened on October 11, 2026; your own client logs and billing pages remain the final evidence.

Choose the endpoint before configuring the client

Goal	Endpoint	Authentication	Best fit
Prove search and fetching work	https://search.parallel.ai/mcp	None	Light exploration at lower anonymous rate limits
Use account credits and higher limits	https://search.parallel.ai/mcp	Bearer API key	Production or account-attributed traffic
Let the client manage browser sign-in	https://search.parallel.ai/mcp-oauth	OAuth or Bearer API key	Enforced authentication without a fixed key in shared config

Two details prevent many false diagnoses. The default /mcp endpoint does not advertise OAuth, so an OAuth-capable client may connect anonymously without opening a browser. The /mcp-oauth endpoint requires authentication and returns 401 to anonymous requests. No login prompt on /mcp is therefore not a failure; a 401 on /mcp-oauth usually means authorization has not completed.

Keep the client, search service, and model provider separate

A single answer can involve three independent paths:

1. The agent client manages the conversation, permissions, tool selection, and UI.
2. Parallel Search MCP performs web_search and web_fetch.
3. The model provider performs reasoning and bills model input, output, and tool-result context.

Adding Search MCP does not replace the model provider. Changing an API Base URL does not automatically add web search. During troubleshooting, ask three different questions: did the client connect to MCP, did the model actually call an MCP tool, and which provider billed the model request?

Claude Code: start with the anonymous endpoint

Run the commands from the project where you use Claude Code:

claude mcp add --transport http "Parallel-Search-MCP" https://search.parallel.ai/mcp
claude mcp get "Parallel-Search-MCP"
claude mcp list

Claude Code writes the server to local scope by default. Add --scope user when you intentionally want it across projects. For team-shared project scope, review .mcp.json and never commit a fixed bearer token.

Inside Claude Code, open the MCP panel:

/mcp

The first useful success signal is a connected status, not merely the CLI’s “Added” message. “Added” means the configuration was written; Connected means the current client can reach the server.

For OAuth, add the same server with this URL instead:

https://search.parallel.ai/mcp-oauth

Then complete authorization from /mcp. Keep /mcp and /mcp-oauth distinct while debugging.

Codex CLI: anonymous, environment-backed bearer, or OAuth

Anonymous setup:

codex mcp add parallel-search --url https://search.parallel.ai/mcp
codex mcp list

For account-backed limits, store PARALLEL_API_KEY through your operating system or secret manager, then let Codex read the environment variable. Do not place the actual key in shell history or the shared config:

codex mcp add parallel-search --url https://search.parallel.ai/mcp \
  --bearer-token-env-var PARALLEL_API_KEY
codex mcp list

For OAuth:

codex mcp add parallel-search --url https://search.parallel.ai/mcp-oauth
codex mcp list

Start a new Codex session after adding the server. Other MCP clients can use the same endpoint, but their configuration schemas differ. VS Code uses a top-level servers object, Cursor commonly uses mcpServers, and some clients require type: "streamable-http". Do not copy one client’s JSON into another without checking its documentation.

Prove which tool was actually called

A connected server proves reachability, not usage in a particular answer. Use a test prompt that must leave observable evidence:

For this check, use Parallel-Search-MCP and do not answer from memory.
1. Call web_search to find the official Parallel Search MCP documentation and current pricing page.
2. Show the source URLs returned by web_search.
3. Select two official URLs and call web_fetch to read their original text.
4. Report the tool name, URL, and one short supporting passage for each source.
If a tool call fails, stop and report the tool name, endpoint, and HTTP status.

Then inspect four layers:

• the transcript or tool trace contains web_search;
• a later event contains web_fetch, rather than only a summary of search results;
• the tool result contains real, openable URLs;
• the final claim can be found in the fetched page content.

A sentence such as “I searched the web” is not evidence. If the client lets you temporarily disable its built-in web-search tool, do so for this isolated test to avoid confusing two tools with similar capabilities. Restore your normal tool set afterward.

Search first, then fetch the original pages

Parallel defines a clear division of labor:

• web_search finds current information and diverse sources. It requires objective and search_queries.
• web_fetch reads known URLs or verifies selected search results. It accepts up to 20 URLs in one request.

When your client exposes or influences tool arguments, use this pattern:

1. Give objective one decision, such as “verify the official anonymous authentication and cost boundaries.”
2. Use two or three short, complementary search_queries; do not paste the whole user prompt into every query.
3. Reuse one session_id within a conversation and create a new value for a new conversation.
4. Keep full_content: false until complete page text is genuinely needed. Full pages can consume tens of thousands of model tokens and may exceed the client’s output limit.
5. Prefer first-party documentation, specifications, and original announcements. Treat community posts as user reports, not universal platform behavior.

This search → select URLs → fetch originals → verify citations loop is more auditable than a generic “look it up” instruction. It also reveals when the model bypasses the tool or relies on a secondary summary.

Cost boundaries: keep at least four ledgers

The prices below were checked against Parallel’s official pricing page on October 11, 2026. They explain billing boundaries; they are not a claim that one option is always cheaper.

Cost layer	Subscription or membership	Minimum top-up	First-month allowance	Usage basis
Anonymous Search MCP	No account subscription is required by the documented anonymous setup	No top-up is required to start anonymously	No fixed call count is published	Documented as free for exploration/light use at lower rate limits; do not assume a permanent or numeric quota
Authenticated Parallel Search/Extract	No separate membership fee is listed on the public pricing page	Not stated on the public pricing page	No fixed introductory credit is stated	Search base price (10 results included per request): fast/turbo US$1 per 1,000 requests; basic/advanced US$5; additional page results and excerpts: US$1 per 1,000 results; Extract: US$1 per 1,000 URLs
Agent client	Depends on Claude Code, Codex, or another client/account	Client-specific	Client-specific	Client plan benefits are not Parallel account credits
Model API	Provider-specific	Provider-specific	Provider-specific	Model input, output, cache, and tool-result context are billed separately from Search MCP

When authenticated traffic returns 402, Parallel’s documentation identifies insufficient account credits. Do not keep retrying the same search. Check the account balance and confirm that the connection is actually using the authenticated path.

Parallel does not publish a fixed anonymous MCP request count on the Search MCP page. The practical capacity test is therefore your own workload record: connection mode, searches and fetched URLs per session, rate-limit events, model-token growth, and the final account bill. Do not copy the general Search API rate-limit table and present it as an anonymous MCP guarantee.

If BetterToken supplies the model, keep both configurations independent

You can retain Claude Code or Codex as the client and add Parallel only as the web-tool layer:

• For Claude Code model calls through BetterToken, the Base URL is https://bettertoken.ai; the client appends /v1/messages, so do not add /v1 yourself.
• For Codex model calls through BetterToken, the Base URL is https://www.bettertoken.ai/v1 with wire_api = "responses".
• The Parallel tool URL remains https://search.parallel.ai/mcp or https://search.parallel.ai/mcp-oauth.

These URLs are not interchangeable. BetterToken handles model requests and token usage; Parallel handles web tools. Anonymous availability, credits, privacy terms, and service limits remain governed by the third-party service. Refer separately to the BetterToken Claude Code guide, BetterToken Codex guide, and Parallel Search MCP documentation.

Common failures and the smallest useful retest

Symptom	Check first	Retest after the fix
Server is added but tools are missing	Fully restart the client; validate config syntax and the exact URL; inspect MCP logs	Confirm both web_search and web_fetch appear
401	Did you use /mcp-oauth; did OAuth finish; is the bearer credential valid?	Reconnect and verify the status no longer requests authentication
402	Authenticated account credits	Add funds or switch back to anonymous /mcp, then run one focused search
Connected, but no tool calls	The agent may choose built-in search or answer from memory	Run the forced test prompt and inspect the tool trace
Fetch output is truncated or huge	full_content, too many URLs, or a broad objective	Disable full content, narrow objective, and fetch only the most relevant pages
Different behavior across projects	Claude Code scope, project approval, or a stale Codex session	List servers again in the target project and repeat the forced call

Decide whether to keep it

Parallel Search MCP is a good long-term fit when you want hosted search and page extraction without maintaining SearXNG or another search stack, your client exposes tool calls and sources, and either the anonymous boundary covers light tasks or you are prepared to budget authenticated usage.

Do not move directly into production when you require a publicly guaranteed fixed free-call count, organization-grade attribution or Zero Data Retention while remaining anonymous, cannot verify actual tool calls, or need full control over indexing, crawling, and data residency.

The safest adoption sequence is: run representative tasks through anonymous /mcp, save the tool traces and source URLs, measure rate-limit behavior and model-token growth, and only then move to Bearer authentication or /mcp-oauth if anonymous limits become the bottleneck. That separates connection success, retrieval quality, third-party usage, and model cost instead of guessing from one blended bill.