Search MCP

The Parallel Search MCP Server provides drop-in web search and content extraction capabilities for any MCP-aware model. The tools invoke the Search API and Extract API endpoints but present a simpler interface to ensure effective use by agents. By default, Search runs in basic mode — tuned for low-latency responses inside agent loops — and total excerpts per tool call are capped to roughly 25,000 characters to stay within typical MCP client output limits. Authenticated clients can configure the search behavior.

The Search MCP is free to use — no API key required, great for exploration and light use. For production use cases or higher rate limits, create a Parallel account and pass your API key as a Bearer token in the Authorization header.

The Search MCP comprises two tools:

web_search — General-purpose web search inside an agent’s reasoning loop. Use when the agent needs current information or diverse sources across multiple angles.
web_fetch — Pulls token-efficient markdown from specific URLs. Use after web_search narrows down candidates, or when the agent already has a URL it needs to read in depth.

One-Click Install

Install in any of the following clients with a single click — no API key required.

Install in Cursor

One-click install for Cursor.

Install in VS Code

One-click install for VS Code.

Install in LM Studio

One-click install for LM Studio.

Install in Goose

One-click install for Goose.

For Claude Code, Codex CLI, Claude Desktop, Windsurf, Zed, Gemini CLI, Warp, Kiro, fx (Vercel), and other clients, see the Installation section below — those clients use a CLI command or a JSON config file rather than deep-link URLs.

Use Cases

The Search MCP is suited for any application where real-world information is needed as part of an AI agent’s reasoning loop. Common use cases include:

Real-time fact checking and verification during conversations
Gathering current information to answer user questions
Researching topics that require recent or live data
Retrieving content from specific URLs to analyze or summarize
Competitive intelligence and market research

Configure search behavior

The Search MCP defaults to basic mode with server-managed search settings. When your MCP request is authenticated with a Parallel API key or OAuth, you can pin Search API settings for every web_search call made through that MCP connection.

Search overrides are ignored for anonymous free-tier requests. Authenticate the /mcp endpoint with a Bearer API key, or use /mcp-oauth, before adding overrides.

The objective and search_queries remain arguments selected by the model for each tool call. Overrides configure how those searches run; they cannot replace what the model searches for. They also do not affect web_fetch.

URL query parameters

Append fields to the MCP server URL. Use the full dotted path for nested fields:

https://search.parallel.ai/mcp?mode=fast&advanced_settings.location=gb&advanced_settings.source_policy.include_domains=wikipedia.org,.gov

For list fields such as include_domains and exclude_domains, use comma-separated values, repeat the parameter, or combine both forms. For example:

?advanced_settings.source_policy.include_domains=wikipedia.org,.gov&advanced_settings.source_policy.include_domains=usa.gov

Configuration header

If your MCP client supports custom headers, send the settings as a JSON object matching the Search API request shape:

Authorization: Bearer <PARALLEL_API_KEY>
x-parallel-search-config: {"mode":"fast","advanced_settings":{"location":"gb","max_results":5}}

Use query parameters for short, easily shareable configurations and the header for larger nested configurations. If both set the same field, the URL query parameter wins. Unrelated header fields are preserved. For example, if the header sets {"mode":"turbo","advanced_settings":{"max_results":5}} and the URL contains ?mode=fast&advanced_settings.location=gb, the effective settings use fast mode, return up to five results, and target Great Britain.

Supported settings

The Search MCP supports the same configurable parameters as the v1 Search API, except objective and search_queries, which remain per-call tool inputs. See Search modes, Source policy, and Advanced Search Settings for the available fields and constraints. The MCP validates these settings against the Search API request schema when the client connects. Unknown fields, invalid values, malformed header JSON, attempts to pin objective or search_queries, and unsupported mode values return an HTTP 400 error during the MCP handshake. Blank query-parameter values are ignored.

Installation

The Search MCP can be installed in any MCP client. Two endpoints are available:

https://search.parallel.ai/mcp — default. Free to use anonymously at lower rate limits. Pass a Parallel API key as a Bearer token (Authorization: Bearer <key>) to unlock higher limits. OAuth is not advertised on this endpoint, so clients that support OAuth sign-in (Claude Desktop, Claude.ai custom connectors, Codex, etc.) will not prompt you to log in here — use /mcp-oauth below if you prefer OAuth.
https://search.parallel.ai/mcp-oauth — the OAuth-capable endpoint. Requires authentication: Bearer API key OR the OAuth flow. Anonymous requests return 401. Use this when you want OAuth instead of managing a Bearer key, or when you need to guarantee every request is attributed to a Parallel account — for example, organization-wide deployments, Zero Data Retention (ZDR) setups, or any context where unauthenticated traffic is not acceptable.

Swap /mcp for /mcp-oauth in any of the config snippets below if you want OAuth or enforced authentication. The Search MCP can also be used programmatically by providing your Parallel API key in the Authorization header as a Bearer token.

Cursor

Add to ~/.cursor/mcp.json or .cursor/mcp.json (project-specific):

{
  "mcpServers": {
    "Parallel Search MCP": {
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

For more details, see the Cursor MCP documentation.

VS Code

The quickest path is the guided flow — no file editing required. Run MCP: Add Server from the Command Palette (⇧⌘P / Ctrl+Shift+P), pick HTTP, and paste the server URL:

https://search.parallel.ai/mcp

VS Code then prompts for a server name (Parallel Search MCP) and whether to add it as Global (available in every workspace) or Workspace (this project only), and writes the configuration for you. Confirm the trust prompt the first time the server starts. To configure it by hand instead, add the following to .vscode/mcp.json in your workspace, or to the user-level mcp.json that the MCP: Open User Configuration command opens:

{
  "servers": {
    "Parallel Search MCP": {
      "type": "http",
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

The user-level mcp.json lives inside your VS Code profile folder, not at ~/.vscode/mcp.json. Open it with MCP: Open User Configuration rather than typing the path — a file you create at ~/.vscode/mcp.json is ignored, with no error to tell you why.

For more details, see the VS Code MCP documentation.

Claude Desktop / Claude.ai

Go to Settings → Connectors → Add Custom Connector, and fill in:

Name: Parallel Search MCP
URL: https://search.parallel.ai/mcp

This URL connects anonymously. If you’d rather sign in with OAuth (so Claude manages the token for you), use https://search.parallel.ai/mcp-oauth instead — it triggers Claude’s OAuth sign-in flow. If you are part of an organization, you may not have access to custom connectors. Contact your organization administrator for assistance.

Org admins (Team / Enterprise plans): to route Claude’s web queries through the Parallel Search MCP instead of Claude’s built-in web search, disable the native web search tool at Admin settings → Capabilities. Once off at the workspace level, members cannot re-enable it individually. See the Claude web search docs.For the org-wide deployment, also point the connector at the /mcp-oauth endpoint (not /mcp) so every request requires a Parallel API key or OAuth — useful when you need every call attributed to the organization.

If you are not an admin, go to Settings → Developer → Edit Config and use the following JSON. If your config already has an mcpServers object, add the Parallel Search MCP entry inside it without replacing your other servers.

{
  "mcpServers": {
    "Parallel Search MCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://search.parallel.ai/mcp"
      ]
    }
  }
}

No API key is required for the Search MCP. To unlock higher rate limits, grab a key from Platform and append "--header", "authorization: Bearer YOUR-PARALLEL-API-KEY" to the args array. For more details, see the Claude remote MCP documentation.

Claude Code

Run this command in your terminal:

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

In Claude code, use the command:

/mcp

Then follow the steps in your browser to login. For more details, see the Claude Code MCP documentation.

Codex CLI

Run one of the following, depending on how you want to authenticate:

Free, anonymous

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

Higher rate limits via API key

# set PARALLEL_API_KEY in your environment first (key from platform.parallel.ai)
codex mcp add parallel-search --url https://search.parallel.ai/mcp \
  --bearer-token-env-var PARALLEL_API_KEY

Higher rate limits via OAuth

codex mcp add parallel-search --url https://search.parallel.ai/mcp-oauth
# complete the browser authorization when prompted

Each command writes the equivalent [mcp_servers.parallel-search] entry to ~/.codex/config.toml — you can also hand-edit it if you prefer. Restart Codex after adding the server. For more details, see the Codex MCP documentation.

fx (Vercel)

fx connects to the Search MCP through mcp-remote. This setup requires Node.js and npx. Run this command inside fx:

/mcp add parallel-search npx -y mcp-remote https://search.parallel.ai/mcp

fx saves the server to ~/.fx/mcp.json without removing your existing MCP servers and reloads the configuration. Run /mcp list to confirm parallel-search shows state=ready. For higher rate limits, get an API key from platform.parallel.ai and export PARALLEL_API_KEY before launching fx. Add "--header" and "Authorization: Bearer ${PARALLEL_API_KEY}" to the parallel-search command array in ~/.fx/mcp.json, then run /mcp reload. For more details, see the fx MCP documentation.

Other Clients

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "serverUrl": "https://search.parallel.ai/mcp"
    }
  }
}

For more details, see the Windsurf MCP documentation.

Cline

Go to MCP Servers → Remote Servers → Edit Configuration:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

For more details, see the Cline MCP documentation.

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "httpUrl": "https://search.parallel.ai/mcp"
    }
  }
}

For more details, see the Gemini CLI MCP documentation.

ChatGPT

Warning: Developer Mode must be enabled, and this feature may not be available to everyone. MCPs in ChatGPT are experimental and may not work reliably.First, go to Settings → Connectors → Advanced Settings, and turn on Developer Mode.Then, in connector settings, click Create and fill in:

Name: Parallel Search MCP
URL: https://search.parallel.ai/mcp
Authentication: OAuth

In a new chat, ensure Developer Mode is turned on with the connector(s) selected.For more details, see the ChatGPT Developer Mode documentation.

Amp

Run this command in your terminal:

amp mcp add "Parallel-Search-MCP" https://search.parallel.ai/mcp

The OAuth flow will start when you start Amp.For more details, see the Amp MCP documentation.

Kiro

Add to .kiro/settings/mcp.json (workspace) or ~/.kiro/settings/mcp.json (global):

{
  "mcpServers": {
    "Parallel Search MCP": {
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

For more details, see the Kiro MCP documentation.

Google Antigravity

In the Antigravity Agent pane, click the menu (⋮) → MCP Servers → Manage MCP Servers → View raw config, then add:

{
  "mcpServers": {
    "Parallel-Search-MCP": {
      "serverUrl": "https://search.parallel.ai/mcp"
    }
  }
}

For higher rate limits, add a headers block with "Authorization": "Bearer YOUR_API_KEY" and your key from platform.parallel.ai.For more details, see the Antigravity MCP documentation.

OpenCode

Add to opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "mcp": {
    "parallel-search": {
      "type": "remote",
      "url": "https://search.parallel.ai/mcp",
      "enabled": true
    }
  }
}

For more details, see the OpenCode MCP documentation.

Roo Code

Add to .roo/mcp.json in your workspace (or edit the global mcp_settings.json from the Roo Code MCP settings view):

{
  "mcpServers": {
    "Parallel Search MCP": {
      "type": "streamable-http",
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

Project config takes precedence over global. For more details, see the Roo Code MCP documentation.

OpenHands

Run this command in your terminal:

openhands mcp add parallel-search --transport http https://search.parallel.ai/mcp

Or add manually to ~/.openhands/mcp.json:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

Inside an OpenHands conversation, use /mcp to verify the server is active. For more details, see the OpenHands MCP documentation.

Factory CLI (droid)

Run this command in your terminal:

droid mcp add parallel-search https://search.parallel.ai/mcp --type http

Inside droid, type /mcp to open the interactive manager and verify the server is connected. For more details, see the Factory MCP documentation.

Pi ships without built-in MCP support, so install the pi-mcp-adapter package first:

pi install npm:pi-mcp-adapter

Restart Pi, then add the Search MCP to .mcp.json in your project (or ~/.config/mcp/mcp.json for a user-global config):

{
  "mcpServers": {
    "parallel-search": {
      "url": "https://search.parallel.ai/mcp",
      "directTools": true
    }
  }
}

directTools: true registers web_search and web_fetch alongside Pi’s built-in tools instead of hiding them behind the adapter’s mcp proxy. Run /mcp inside Pi to verify the server is detected. For more details, see the pi-mcp-adapter README.Alternatively, skip MCP entirely and use the Parallel CLI as a Pi skill — that’s the same pattern as our ClawHub / OpenClaw integration.

OpenClaw

OpenClaw stores MCP server definitions in ~/.openclaw/openclaw.json under mcp.servers. Save the Search MCP via the openclaw mcp set CLI:

openclaw mcp set parallel-search '{"url":"https://search.parallel.ai/mcp","transport":"streamable-http"}'

Or edit ~/.openclaw/openclaw.json directly:

{
  "mcp": {
    "servers": {
      "parallel-search": {
        "url": "https://search.parallel.ai/mcp",
        "transport": "streamable-http"
      }
    }
  }
}

The transport field is required — OpenClaw defaults to SSE when it’s omitted, but the Search MCP uses Streamable HTTP. No API key is required; for higher rate limits, add an optional headers map with "Authorization": "Bearer YOUR-PARALLEL-API-KEY" (key from platform.parallel.ai).openclaw mcp set only writes to config — it doesn’t connect to the server or reload running agents. Start a new OpenClaw agent session (or restart your current one) for the tools to show up. Verify the saved definition with openclaw mcp list / openclaw mcp show parallel-search. For the full MCP CLI reference, see the OpenClaw MCP docs.You can also skip MCP entirely and use the Parallel CLI as an OpenClaw skill — see the ClawHub integration.

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  parallel_search:
    url: "https://search.parallel.ai/mcp"

For more details, see the Hermes Agent MCP documentation.

Continue.dev

Add a file at .continue/mcpServers/parallel-search.yaml in your workspace:

name: Parallel Search MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: Parallel Search MCP
    type: streamable-http
    url: https://search.parallel.ai/mcp

For more details, see the Continue.dev MCP documentation.

Zed, Warp, Raycast (stdio-only clients)

These clients currently support only stdio-transport MCP servers — they can’t connect directly to remote HTTP endpoints. Wrap the Search MCP with mcp-remote to proxy it through a local stdio process:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://search.parallel.ai/mcp"]
    }
  }
}

Add an --header "Authorization: Bearer YOUR-PARALLEL-API-KEY" argument if you’re hitting /mcp-oauth or want higher rate limits.Placement differs per client — see the Zed MCP docs, Warp MCP docs, or Raycast MCP docs for the exact file location and wrapper format.

If your client isn’t listed, most MCP clients accept the mcpServers format shown in the Cursor section. For clients that use a different wrapper (e.g., VS Code’s top-level servers, Windsurf’s serverUrl), check the client’s documentation for the correct field names.

Best practices

Filtering by date or domain

For flexible date or domain preferences, include the constraints directly in the search query or objective. This gives the model room to find relevant sources without unnecessarily excluding the rest of the web. For example:

“Latest AI research papers from 2026”
“News about climate change from nytimes.com”
“Product announcements from apple.com in the last month”

If your authenticated deployment requires a hard constraint, pin advanced_settings.source_policy.after_date, advanced_settings.source_policy.include_domains, or advanced_settings.source_policy.exclude_domains using Search MCP overrides. Because the configuration applies to every web_search call on that connection, reserve hard filters for requirements that should apply throughout the session.

Source-policy fields are hard filters and can significantly reduce result quality. Prefer natural-language guidance unless your application must include or exclude specific domains.

Troubleshooting

Common Installation Issues

Cline: 'Authorization Error redirect_uri must be https'

This error occurs when Cline attempts OAuth authentication but the redirect URI isn’t using HTTPS. The Search MCP at /mcp is free and doesn’t require OAuth in the first place — wrap it in mcp-remote so Cline treats it as a plain stdio server:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://search.parallel.ai/mcp"
      ]
    }
  }
}

If you want higher rate limits (or you’re specifically targeting /mcp-oauth), append "--header", "authorization: Bearer YOUR-PARALLEL-API-KEY" to the args array with a key from platform.parallel.ai.

Gemini CLI: Where to provide API key

Gemini CLI uses HTTP MCPs and can authenticate via OAuth. The Search MCP at /mcp doesn’t require an API key or OAuth, so the simplest setup has no auth at all:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "httpUrl": "https://search.parallel.ai/mcp"
    }
  }
}

Add this to ~/.gemini/settings.json. If you want higher rate limits (or to target /mcp-oauth), swap in the mcp-remote wrapper and pass a key from platform.parallel.ai as a Bearer header:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://search.parallel.ai/mcp",
        "--header",
        "authorization: Bearer YOUR-PARALLEL-API-KEY"
      ]
    }
  }
}

VS Code: Server not detected (wrong file location)

VS Code reads two mcp.json locations: .vscode/mcp.json inside the workspace, and a user-level mcp.json in your VS Code profile folder, which the MCP: Open User Configuration command opens. ~/.vscode/mcp.json is not one of them — that directory holds argv.json and your installed extensions, so a server defined there never loads and VS Code reports no error.If a hand-written config isn’t picked up, run MCP: Open User Configuration and check whether the file that opens is the one you edited. Run MCP: List Servers to confirm VS Code sees the server, and use MCP: Add Server to let VS Code write the entry to the correct file.

VS Code: Incorrect configuration format

VS Code’s mcp.json uses a different structure than Cursor’s mcp.json. Common mistake: copying a Cursor-style config into VS Code.Incorrect (Cursor format):

{
  "mcpServers": {
    "parallel-search": {
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

Correct (VS Code format, .vscode/mcp.json or user-level mcp.json):

{
  "servers": {
    "Parallel Search MCP": {
      "type": "http",
      "url": "https://search.parallel.ai/mcp"
    }
  }
}

Note: VS Code uses a top-level servers object (not mcpServers) and includes type: "http" for remote HTTP servers.

Windsurf: Configuration location and format

Windsurf uses a different configuration format than Cursor.Correct Windsurf configuration:

{
  "mcpServers": {
    "Parallel Search MCP": {
      "serverUrl": "https://search.parallel.ai/mcp"
    }
  }
}

Note: Windsurf uses serverUrl instead of url. Add this to your Windsurf MCP configuration file.

Connection timeout or 'server unavailable' errors

If you’re getting connection errors:

Check your network: Ensure you can reach https://search.parallel.ai
Verify API key: Make sure your key is valid at platform.parallel.ai
Check balance: A 402 error means insufficient credits—add funds to your account
Restart your IDE: Some clients cache MCP connections

Tools not appearing in the IDE

If the MCP installs but tools don’t show up:

Restart your IDE completely (not just reload)
Check configuration syntax: Ensure valid JSON with no trailing commas
Verify the server URL: Must be exactly https://search.parallel.ai/mcp
Check IDE logs: Look for MCP-related errors in your IDE’s output/debug panel

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

One-Click Install

Install in Cursor

Install in VS Code

Install in LM Studio

Install in Goose

Use Cases

Configure search behavior

URL query parameters

Configuration header

Supported settings

Installation

Cursor

VS Code

Claude Desktop / Claude.ai

Claude Code

Codex CLI

fx (Vercel)

Other Clients

Best practices

Filtering by date or domain

Troubleshooting

Common Installation Issues

​One-Click Install

Install in Cursor

Install in VS Code

Install in LM Studio

Install in Goose

​Use Cases

​Configure search behavior

​URL query parameters

​Configuration header

​Supported settings

​Installation

​Cursor

​VS Code

​Claude Desktop / Claude.ai

​Claude Code

​Codex CLI

​fx (Vercel)

​Other Clients

​Best practices

​Filtering by date or domain

​Troubleshooting

​Common Installation Issues

One-Click Install

Use Cases

Configure search behavior

URL query parameters

Configuration header

Supported settings

Installation

Cursor

VS Code

Claude Desktop / Claude.ai

Claude Code

Codex CLI

fx (Vercel)

Other Clients

Best practices

Filtering by date or domain

Troubleshooting

Common Installation Issues