For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
The Parallel MCP server gives Claude, ChatGPT, Cursor, Codex, and any other MCP client web search, page fetch, and research through one URL:
.md to its URL or sending Accept: text/markdown.For Search and Extract, use /v1/search and /v1/extract for all new integrations and agent tool calls. Use /v1beta/search and /v1beta/extract only when maintaining an existing integration that already uses them. The request bodies changed too: on /v1/extract, full_content, fetch_policy and excerpt_settings go inside advanced_settings, and sending the v1beta top-level excerpts, full_content and fetch_policy to /v1/extract returns a 422. On /v1/search, search_queries is required (at least one short keyword query), and max_results, source_policy and fetch_policy go inside advanced_settings; sending only objective, or sending those fields at the top level, returns a 422. Do not substitute /v1 for the documented FindAll or Ingest endpoint paths.If you are evaluating Parallel Search or comparing it with other search APIs, read How to Eval Parallel Search before you build the harness, especially its Common pitfalls section. The most common mistake is sending the raw question as both objective and the only entry in search_queries. Write a goal-style objective and 1-3 short keyword queries instead.web_search, web_fetch, web_decisions, and image_search in fast mode 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, or copy a setup prompt for any other agent, from parallel.ai/mcp.
web_search, web_fetch, web_decisions, image_search, find_verticals, and search_vertical. 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.
Authentication
The server supports three authentication methods:OAuth sign-in
Connect tohttps://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.
/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: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, after any free usage your account includes. 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
The following table covers the core web tools, not every tool the server exposes.
By default, the tools the server lists include
web_search, web_fetch, web_decisions, image_search, find_verticals, and search_vertical, 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. Override settings can also set Search API fields that aren’t tool arguments, such as advanced_settings.max_results and advanced_settings.source_policy.include_domains.
Arguments
Arguments
web_fetch
web_fetch calls the Extract API.
Arguments
Arguments
advanced_settings.excerpt_settings.max_chars_per_result and advanced_settings.fetch_policy.max_age_seconds, use override settings.
web_research
web_research calls the Responses API and returns when the answer is ready.
Arguments
Arguments
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
Arguments
Arguments
type, instructions, and criteria for its type:
See Question Types for example answers.
Example arguments
image_search
image_search calls the Images API and returns direct image URLs, the page each image appears on, the page title, and pixel dimensions when known. Results link to images but don’t describe them. For information about a subject, use web_search.
Arguments
Arguments
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 tools the server lists includeweb_search, web_fetch, web_decisions, image_search, find_verticals, and search_vertical, 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:
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 thex-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
401.overridesets fields of the tool’s API request.overrideis a JSON Merge Patch: objects merge,nullremoves a field, and any other value replaces the existing value. The server appliesoverridelast, so the model can’t change these values.model_choicelists 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 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
- image_search
Fields of the Search API request:
Validation and limits
- When a
model_choicepath 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’sfull_contentargument setsadvanced_settings.full_content, andweb_research’sreasoning_effortargument setsreasoning.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_researchtoolsentries inoverridethat includeauthorizationorheaders. - The server doesn’t support the Search MCP’s
x-parallel-search-configheader, and it ignores URL query parameters other thanloginandtools, such as the Search MCP’s?mode=.
Client examples
The following examples setmode to basic for every web_search call:
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/mcptohttps://mcp.parallel.ai/mcp, andhttps://search.parallel.ai/mcp-oauthtohttps://mcp.parallel.ai/mcp?login. Theweb_searchandweb_fetchtools keep their names. Move settings from URL query parameters or thex-parallel-search-configheader to thex-parallel-mcp-configheader. 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.