Parallel MCP Server

The Parallel MCP server gives Claude, ChatGPT, Cursor, Codex, and any other MCP client web search, page fetch, and research through one URL:

https://mcp.parallel.ai/mcp

No API key is required to get started: web_search, web_fetch, and web_decisions are free at lower rate limits. web_research requires authentication.

Installation

One-click install for Claude, ChatGPT, Cursor, and VS Code

Add Parallel to your app in one click from parallel.ai/mcp.

Add the server to Claude Code or Codex with one command:

claude mcp add --transport http parallel https://mcp.parallel.ai/mcp

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

The commands connect without a key, with access to web_search and web_fetch. To sign in or use an API key, see Authentication. For other clients, such as Gemini CLI, Windsurf, and Zed, see the client installation guide. To call the server from your own code, see Programmatic use.

Looking for help with Parallel documentation? Try our Docs MCP to get AI-assisted answers about Parallel’s documentation. The Docs MCP searches our docs only and doesn’t call Parallel APIs.

Agent installation prompt

Paste the following prompt into a chat app like ChatGPT or Claude, or into a coding agent like Claude Code, Cursor, or Codex. The agent finds Parallel’s official plugin for its app or adds the MCP server for you.

Parallel MCP install prompt

Set up Parallel Search so that you, the agent I'm talking to right now, can use it for web search.

1. Identify the app you are running in, for example ChatGPT, Claude, Claude Code, Codex, Cursor, VS Code Copilot, Gemini CLI, OpenClaw, or Hermes Agent.

2. Unless you are in Cursor, look for Parallel's official plugin, connector, app, or extension for that app. Use your built-in web search with a query like "parallel web search <app name> plugin". In ChatGPT, for example, search "parallel web search ChatGPT plugin". Only trust results from parallel.ai, docs.parallel.ai, github.com/parallel-web, or the app's own official directory. Known ones:
- ChatGPT: https://chatgpt.com/plugins/plugin_asdk_app_69fb9378663481919a68e8a2109644e5
- Claude and Claude Desktop: https://claude.com/marketplace/connectors/parallel-search
- Gemini CLI: gemini extensions install https://github.com/parallel-web/search-mcp
- Hermes Agent: hermes plugins install parallel-search
If you find one, follow its official install steps. If I have to click Install or approve access myself, give me the direct link and the exact steps, then wait for me.

3. If you are in Cursor, or your app has no official Parallel integration, add the Parallel Search MCP server to your own MCP config, not to another app's:
- Server name: parallel
- Server URL: https://mcp.parallel.ai/mcp
- Transport: Streamable HTTP
- Authentication: none. It is free without an API key.
Use the method your app expects, for example `claude mcp add --transport http parallel https://mcp.parallel.ai/mcp` in Claude Code or `codex mcp add parallel --url https://mcp.parallel.ai/mcp` in Codex. Steps for each app are at https://docs.parallel.ai/integrations/mcp/installation

4. Do not set up an API key or OAuth unless I ask. For higher rate limits I can create an account at https://platform.parallel.ai and use my API key as a Bearer token, or connect to https://mcp.parallel.ai/mcp?login (OAuth flow).

5. Tell me which option you chose and whether I need to restart the app. Once the tools load, confirm that web_search and web_fetch are available, run one test search, and give me a source link.

Authentication

The server supports three authentication methods:

Method	Use case	Setup
No key	Free, rate-limited access to `web_search`, `web_fetch`, and `web_decisions`	Connect to `https://mcp.parallel.ai/mcp`.
OAuth sign-in	Access to `web_research` and higher rate limits in clients that support MCP OAuth	Connect to `https://mcp.parallel.ai/mcp?login`.
API key	Clients without MCP OAuth support, and calls from your own code	Connect to `https://mcp.parallel.ai/mcp` and send the key in a request header.

Connect to https://mcp.parallel.ai/mcp?login from any client that supports MCP OAuth, such as Claude, ChatGPT, Claude Code, Codex, and Cursor. The client opens a browser window to sign in with your Parallel account and stores the token.

claude mcp add --transport http parallel 'https://mcp.parallel.ai/mcp?login'

codex mcp add parallel --url 'https://mcp.parallel.ai/mcp?login'

Codex opens the sign-in page when you add the server. In Claude Code, run /mcp, select parallel, and sign in. Quote the URL in shell commands, because ? and & are special characters in most shells.

API key

Create a key on Platform, then send the key in either of the following headers:

Authorization: Bearer YOUR_PARALLEL_API_KEY
x-api-key: YOUR_PARALLEL_API_KEY

claude mcp add --transport http parallel https://mcp.parallel.ai/mcp \
  --header 'Authorization: Bearer ${PARALLEL_API_KEY}'

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

{
  "mcpServers": {
    "Parallel": {
      "url": "https://mcp.parallel.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PARALLEL_API_KEY}"
      }
    }
  }
}

Each example reads the key from the PARALLEL_API_KEY environment variable when the client connects, so the key isn’t written to the client’s configuration. For other clients, see the client installation guide.

Billing

Calls made with OAuth sign-in or an API key are billed to your Parallel account at the same rates as the underlying API. Each tool result reports its cost in _meta["parallel/usage"], with one entry per SKU that lists name, count, and cost_usd. Calls without a key are free and don’t report usage.

Tools

Tool	Description	Authentication
`web_search`	Searches the web and returns excerpts that usually contain enough information to answer the question.	Not required
`web_fetch`	Reads specific URLs and returns the relevant parts of each page, or the full page as markdown.	Not required
`web_research`	Researches a single question and returns an answer with citations in the same call.	Required
`web_decisions`	Answers typed questions about a subject, such as a probability, a choice between options, or a score, from current web evidence.	Not required

By default, the server lists web_search, web_fetch, and web_decisions, plus web_research with OAuth sign-in or an API key.

`web_search`

web_search calls the Search API. Searches use fast mode unless an override setting specifies a different mode.

Arguments

Argument	Type	Required	Description
`objective`	string	Yes	A natural-language description of what the search should find. Keep it to one goal. The objective can name preferred sources or how recent results should be.
`search_queries`	string[]	Yes	Keyword queries of 3–6 words each. At least one query is required; 2–3 queries work best. Search operators are supported.
`client_model`	string	No	Available on connections without a key. The exact, versioned name of the model making the call, up to 100 characters. Models that aren’t sure of their exact name leave it out. Used for analytics.
`session_id`	string	No	Available on connections without a key. The `session_id` returned by an earlier `web_search` or `web_fetch` result in the same conversation, up to 1,000 characters. Leave it out on the first call. Used to correlate tool calls.

`web_fetch`

web_fetch calls the Extract API.

Arguments

Argument	Type	Required	Default	Description
`urls`	string[]	Yes	—	HTTP or HTTPS URLs to read, up to 20 per call.
`objective`	string	No	`null`	A description of what to look for in the pages, up to 200 characters.
`search_queries`	string[]	No	`null`	Keyword queries of 3–6 words each that focus the excerpts. When fetching results from `web_search`, pass the same queries.
`full_content`	boolean	No	`false`	Returns the whole page as markdown. A long page can reach tens of thousands of tokens and exceed the client’s tool-output limit.
`allow_live_fetch`	boolean	No	`true`	When `false`, returns cached content only. Cached responses are faster but can be older.
`client_model`	string	No	—	Available on connections without a key. Same as on `web_search`.
`session_id`	string	No	—	Available on connections without a key. Same as on `web_search`.

`web_research`

web_research calls the Responses API and returns when the answer is ready.

Arguments

Argument	Type	Required	Default	Description
`input`	string	Yes	—	The research question, up to 20,000 characters.
`reasoning_effort`	string	No	`auto`	`low`, `medium`, `high`, or `auto`. With `auto`, the server picks the effort for each question.
`previous_response_id`	string	No	`null`	The response ID from an earlier `web_research` call, to continue that research.

Each web_research result contains the full Responses API response, including its id. To ask a follow-up that builds on earlier research, pass that id as previous_response_id. The follow-up inherits the earlier question and answer, so the new question can refer to earlier findings without restating the original question. Follow-ups aren’t available for organizations with Zero Data Retention (ZDR) enabled. See Statefulness.

`web_decisions`

web_decisions calls the Decisions API, which takes context and named questions, retrieves web evidence, and returns typed answers with sources. Pass the context in state and up to 100 questions in questions. Since web_decisions is an early release, we recommend being explicit about using it when you prompt your agent. For example:

Example prompt

Use Parallel Decisions to check whether Parallel supports data residency in Europe.

Arguments

Argument	Type	Required	Default	Description
`state`	JSON	Yes	—	Shared context for the questions, for example `{"company": "Parallel"}`.
`questions`	object	Yes	—	1–100 questions, keyed by names you choose. Names may contain only ASCII letters, numbers, underscores, and hyphens.
`include_excerpts`	boolean	No	`false`	Whether each citation includes excerpts. Excerpts often add more than 15,000 characters to a response. URLs and available titles are returned either way.

Each question has a type, instructions, and criteria for its type:

Type	Use it for	Result	`criteria`
`noul`	A statement that can be true or false	Estimated probability from 0 to 1	Optional. `true` and `false` descriptions.
`choice`	Selecting from named categories	One criteria key and probabilities for the options	Required. 2–255 options.
`score`	Rating against ordered criteria	Probability-weighted mean of the level indices	Required. 2–10 levels, lowest first.

See Question Types for example answers.

Example arguments

{
  "state": { "company": "Parallel", "website": "https://parallel.ai" },
  "questions": {
    "eu_data_residency": {
      "type": "noul",
      "instructions": "Does Parallel support data residency in Europe?"
    },
    "eu_residency_availability": {
      "type": "choice",
      "instructions": "What is the availability of data residency in Europe for Parallel? Select unknown when evidence is insufficient.",
      "criteria": {
        "documented": "Parallel publicly documents data residency in Europe.",
        "unavailable": "Parallel explicitly states that data residency in Europe is not offered.",
        "unknown": "The evidence does not establish whether Parallel offers data residency in Europe."
      }
    }
  }
}

Any question can return a refusal instead of an answer. Each question, including the shared state, may use at most 32,000 estimated input tokens. Each tool rejects arguments that aren’t in its input schema. The error message lists the arguments the tool accepts, which helps models in clients that don’t show input schemas.

Configuration

The server works without configuration. Tool selection changes which tools a client sees, and override settings change the API requests that each tool sends.

Tool selection

By default, the server lists web_search, web_fetch, and web_decisions, plus web_research with OAuth sign-in or an API key. To choose the tools, add the tools query parameter with a comma-separated list of tool names:

https://mcp.parallel.ai/mcp?tools=web_search
https://mcp.parallel.ai/mcp?tools=web_search,web_decisions
https://mcp.parallel.ai/mcp?login&tools=web_search,web_research

A tool list replaces the default list, so include every tool the client should see. Tool names must match exactly and can’t contain spaces. An unknown tool name or a repeated tools parameter returns HTTP 400, and a URL with a trailing slash, such as https://mcp.parallel.ai/mcp/, returns HTTP 404.

Override settings

Override settings set API request fields for every call on a connection. Override settings can also expose additional request fields to the model as tool arguments. Send override settings as a JSON object in the x-parallel-mcp-config request header.

Override settings require an API key or OAuth sign-in, and an MCP client that can send custom headers. A request without credentials that includes the header receives HTTP 400.

The JSON object is keyed by tool name. Each tool accepts two optional fields:

override sets fields of the tool’s API request. override is a JSON Merge Patch: objects merge, null removes a field, and any other value replaces the existing value. The server applies override last, so the model can’t change these values.
model_choice lists dotted field paths that the model can set. Each exposed top-level field becomes a tool argument with the same name. Paths can traverse objects but not lists or unions.

{
  "web_search": {
    "override": {
      "mode": "basic",
      "advanced_settings": {
        "source_policy": { "exclude_domains": ["reddit.com"] }
      }
    },
    "model_choice": ["advanced_settings.source_policy.include_domains"]
  },
  "web_research": {
    "override": {
      "reasoning": { "effort": "low" },
      "text": { "verbosity": "low" }
    }
  }
}

In this example, every web_search call uses basic mode and excludes reddit.com, and the model can pass include_domains on each call. Every web_research call uses low reasoning effort and low verbosity.

Supported fields

override and model_choice accept any field of the tool’s API request. The following tables list the most common fields.

web_search
web_fetch
web_research
web_decisions

Fields of the Search API request:

Field	Description
`mode`	`turbo`, `fast`, `basic`, or `advanced`. The MCP server defaults to `fast`. See Search modes.
`advanced_settings.max_results`	Maximum number of results. Defaults to 10.
`advanced_settings.location`	ISO 3166-1 alpha-2 country code for geo-targeted results, such as `gb`.
`advanced_settings.source_policy.include_domains`	Domains or domain/path prefixes that results must come from.
`advanced_settings.source_policy.exclude_domains`	Domains or domain/path prefixes to exclude. Ignored when `include_domains` is set.
`advanced_settings.source_policy.after_date`	Earliest publication date for results, as `YYYY-MM-DD`.
`advanced_settings.excerpt_settings.max_chars_per_result`	Maximum excerpt characters per result.
`max_chars_total`	Maximum excerpt characters across all results.
`advanced_settings.fetch_policy.max_age_seconds`	Maximum age of cached content before the server fetches a live copy. Minimum 600.

Fields of the Extract API request:

Field	Description
`advanced_settings.full_content`	`true`, `false`, or `{"max_chars_per_result": n}` to limit full content per page.
`advanced_settings.excerpt_settings.max_chars_per_result`	Maximum excerpt characters per URL.
`max_chars_total`	Maximum excerpt characters across all URLs.
`advanced_settings.fetch_policy.max_age_seconds`	Maximum age of cached content before the server fetches a live copy. Minimum 600.
`advanced_settings.fetch_policy.timeout_seconds`	Timeout for a live fetch, in seconds.
`advanced_settings.fetch_policy.disable_cache_fallback`	When `true`, a failed live fetch returns an error instead of older cached content.

Fields of the Responses API request:

Field	Description
`reasoning.effort`	`low`, `medium`, or `high`.
`text.verbosity`	`low`, `medium`, or `high`.
`instructions`	System instructions for every research call.
`tools`	A `web_search` tool with `filters` that restrict the domains searched and cited. See Web search tool.
`data_sources`	Data partners to query in addition to web search. See Data connectors.

Fields of the Decisions API request:

Field	Description
`include_excerpts`	Whether each citation includes excerpts.

Validation and limits

When a model_choice path covers the field behind one of a tool’s own arguments, the exposed field replaces that argument, so the model sees one control per field. For example, web_fetch’s full_content argument sets advanced_settings.full_content, and web_research’s reasoning_effort argument sets reasoning.effort.
The server validates the header when the client connects. Unknown fields, paths through lists or unions, and invalid Search values return HTTP 400. Other invalid values return a tool error when the tool runs.
Don’t include credentials in the header. The server rejects web_research tools entries in override that include authorization or headers.
The server doesn’t support the Search MCP’s x-parallel-search-config header, and it ignores URL query parameters other than login and tools, such as the Search MCP’s ?mode=.

Source-policy fields are hard filters and can reduce result quality. For flexible preferences, such as “from the last month” or “from nytimes.com”, include the preference in the search objective or queries. Reserve source-policy overrides for requirements that apply to the whole session.

Client examples

The following examples set mode to basic for every web_search call:

claude mcp add --transport http parallel https://mcp.parallel.ai/mcp \
  --header "Authorization: Bearer $PARALLEL_API_KEY" \
  --header 'x-parallel-mcp-config: {"web_search":{"override":{"mode":"basic"}}}'

{
  "mcpServers": {
    "Parallel": {
      "url": "https://mcp.parallel.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PARALLEL_API_KEY}",
        "x-parallel-mcp-config": "{\"web_search\":{\"override\":{\"mode\":\"basic\"}}}"
      }
    }
  }
}

tools = [
    {
        "type": "mcp",
        "server_label": "parallel",
        "server_url": "https://mcp.parallel.ai/mcp",
        "headers": {
            "Authorization": f"Bearer {os.environ['PARALLEL_API_KEY']}",
            "x-parallel-mcp-config": json.dumps(
                {"web_search": {"override": {"mode": "basic"}}}
            ),
        },
        "require_approval": "never",
    }
]

Migration from the Search MCP and Task MCP

The Parallel MCP server replaces the standalone Search MCP (search.parallel.ai/mcp) and Task MCP (task-mcp.parallel.ai/mcp) for new installations. Both standalone servers continue to run.

Search MCP: Change https://search.parallel.ai/mcp to https://mcp.parallel.ai/mcp, and https://search.parallel.ai/mcp-oauth to https://mcp.parallel.ai/mcp?login. The web_search and web_fetch tools keep their names. Move settings from URL query parameters or the x-parallel-search-config header to the x-parallel-mcp-config header. The new server ignores the old query parameters.
Task MCP: For single research questions, use web_research, which returns the answer in the same call without polling. For asynchronous deep research reports and enrichment of lists, continue to use the Task MCP, or call the Task API or the Parallel CLI directly.

Documentation for the standalone servers remains available: Search MCP and Task MCP.

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

Parallel MCP Server

Installation

One-click install for Claude, ChatGPT, Cursor, and VS Code

Agent installation prompt

Authentication

API key

Billing

Tools

`web_search`

`web_fetch`

`web_research`

`web_decisions`

Configuration

Tool selection

Override settings

Supported fields

Validation and limits

Client examples

Migration from the Search MCP and Task MCP

​Installation

One-click install for Claude, ChatGPT, Cursor, and VS Code

​Agent installation prompt

​Authentication

​OAuth sign-in

​API key

​Billing

​Tools

​web_search

​web_fetch

​web_research

​web_decisions

​Configuration

​Tool selection

​Override settings

​Supported fields

​Validation and limits

​Client examples

​Migration from the Search MCP and Task MCP

Installation

Agent installation prompt

Authentication

OAuth sign-in

API key

Billing

Tools

`web_search`

`web_fetch`

`web_research`

`web_decisions`

Configuration

Tool selection

Override settings

Supported fields

Validation and limits

Client examples

Migration from the Search MCP and Task MCP