Most MCP clients (Claude Code, Claude Desktop Connectors UI, Cursor,
VS Code, Windsurf, Cline) just need the URL — OAuth handles auth on
first use. Previous recipe led with the mcp-remote stdio bridge +
inline API key + Claude Desktop shell-env gotchas, which only apply to
older clients without remote-HTTP support.
Now:
- URL-first, one config block per client, tiny snippets
- mcp-remote bridge demoted to a 'Stdio fallback' section at the bottom
- Per-client quirks captured in one line each (Windsurf uses serverUrl,
Cline needs type=streamableHttp, VS Code wraps in mcp.servers)
- Points at docs.parallel.ai/integrations/mcp/search-mcp for any client
not listed.
Pulled concrete, often counterintuitive guidance from the dedicated docs
pages into the SKILL.md guardrails and the per-language recipes, with
deep-dive links in each API section rather than paraphrasing.
Highlights:
- Task output schemas: every property must be in 'required', use
{type: ['string','null']} union for optional fields, always set
additionalProperties: false, root must be type: object.
- FindAll: if you get 0 matches, UPGRADE the generator before rewriting
the query — issue is usually pool size, not query quality. Match
generator to expected volume (base/core/pro guidance).
- Search / Extract: session_id groups related calls, client_model
enables server-side optimization for the consuming LLM. Expose only
objective + search_queries as LLM tool params.
- Extract: warning that full_content without objective is redundant.
- Added a 'Canonical best-practice pages' block in SKILL.md linking to
Search/Extract/Task/FindAll/MCP best-practice docs.
The hosted Search MCP is launching at search.parallel.ai/mcp rather than
search-mcp.parallel.ai/mcp. Updated all references in the MCP recipe:
remote URL configs for Cursor / VS Code / Claude Desktop, the Claude Code
CLI install commands, and the programmatic Bearer-token example.
Follow-up from eval feedback:
- Python recipe now pins 'parallel-web>=0.5,<1.0' (both evals hit install
friction without a pin).
- TS recipe pins 'parallel-web@^0.4' with a response-shape cheat-sheet.
- Python recipe documents how to import APIError/RateLimitError and the
optional TaskSpecParam/JsonSchemaParam TypedDicts for strict pyright.
- Documents result.output.content shape (flagged as a guess by both evals).
- Adds a Task Group batch-enrichment snippet for the 50+ row case.
Mirrors the /onboarding-guest landing-page experience as a user-invocable
skill: when a user says "integrate Parallel" / "add Parallel to my app",
the agent picks the matching API (Search / Task / FindAll / Monitor /
Extract) and client (Python / TypeScript / cURL / MCP), then emits install
+ env + a working code example with best-practice comments inline.
Structure (progressive disclosure per the Agent Skills spec):
- SKILL.md (71 lines): decision table, guardrails, and routing to a
per-client recipe file.
- references/python.md: client.search, client.task_run (research +
enrichment), client.beta.findall, client.extract, and an httpx
fallback for the alpha Monitor API.
- references/typescript.md: same surface, with explicit guardrails that
the TS SDK uses snake_case body fields (task_spec, output_schema,
run_id) and a tsconfig note for the private-field lib-check issue.
- references/curl.md: raw HTTP equivalents with the correct endpoint
versions (v1, v1beta, v1alpha).
- references/mcp.md: Claude Code / Cursor / VS Code / Claude Desktop
configs for the hosted Search + Task MCP servers, including the
macOS Claude Desktop gotchas (env inheritance, npx PATH, relaunch).
Complements, rather than replaces, the existing runtime skills
(parallel-web-search, parallel-deep-research, parallel-data-enrichment,
parallel-web-extract): those invoke parallel-cli to get work done now;
this one writes code the user will ship.
Bumps plugin + marketplace version to 0.3.0.
* Add OpenAI Codex plugin support (dual-manifest)
Add .codex-plugin/plugin.json manifest and .agents/plugins/marketplace.json
for Codex compatibility. Skills directory is shared between both platforms.
* Add .agents/skills symlinks for Codex skill discovery
Codex scans .agents/skills/ at the repo root for skill auto-discovery.
Symlinks point back to the shared skills/ directory so both platforms
read the same SKILL.md files. Codex docs confirm symlink support.
* Direct agent to read from output file instead of stdout
Codex truncates stdout via max_output_tokens on tool calls, so the
JSON results get cut off. The -o flag already saves full results to
file — instruct the agent to read from there instead.
* Tell agent not to cap output tokens on parallel-cli commands
The CLI already bounds output via --max-results and
--excerpt-max-chars-total. Adding max_output_tokens on the tool call
creates a second truncation layer that breaks JSON parsing.
* Add Codex installation instructions to README
* Fix enrichment skill: add --output to poll command
The --target flag on enrich run doesn't carry over to the poll step,
so the output CSV was never written. The poll command needs its own
--output flag to save results.
* Add --json flag to enrich run commands
Without --json, the CLI output isn't structured and the interaction_id
can't be parsed for multi-turn context chaining.
* Add interaction ID support for multi-turn research and enrichment
The CLI now returns interaction_id values that can chain context across
turns. This updates skills to extract and surface interaction IDs, and
to pass --previous-interaction-id on follow-up queries. Enables flows
like search → deep research, research → enrichment, and multi-turn
deep research sessions where pronouns like "they" or "that" resolve
from prior context.
* Revert web-search interaction_id changes — search API doesn't return one
Search uses a different API path (returns search_id, not interaction_id).
Only research run and enrich run support interaction chaining.
* Use docs language for interaction chaining, recommend lite processor for follow-ups
Follow-ups use --processor lite since the heavy research was already done
in the initial turn. Language aligned with docs.parallel.ai.
* Remove search from interaction_id references — only research and enrichment support it
* Consolidate commands into skills after Claude Code v2.1.3 merge
Claude Code v2.1.3 merged slash commands and skills into a unified
model. Remove the commands/ directory and convert the 3 standalone
commands (setup, status, result) into proper skills. The 4 wrapper
commands that just delegated to skills are no longer needed. Add
user-invocable and argument-hint frontmatter to all skills. Bump
version to 0.2.0.
* Use parallel-subagent for search and extract skills
Adds agent: parallel-subagent to the forked search and extract skills,
scoping them to Bash-only instead of the default general-purpose agent.
* Qualify agent reference with plugin namespace
Use parallel:parallel-subagent instead of bare parallel-subagent
since the agent is defined in this plugin, not in .claude/agents/.
Some environments can't use the install script (e.g. no curl, network
restrictions). Add pipx as a fallback install method across all skills
and the setup command.
context: fork now works in Claude Code, so the "Claude Code" sections
that manually spawned subagents via the Task tool are redundant. Replace
with agent: parallel-subagent in frontmatter to use the correct agent
type for the fork.
Matt Harris