Firecrawl MCP Server

Firecrawl agent

firecrawl_agent

Run multi-site web research when URLs are unknown, returning structured JSON assembled across sources. Provide a prompt, optional schema, and seed URLs to build entity profiles or datasets.

Instructions

Run web research that returns structured data when the URLs are not known or the answer spans several sites. Describe the fields you need in prompt, optionally pass a JSON schema and seed urls, and the research agent searches, navigates, reads pages, and returns JSON assembled across sources. Use it to research an entity plus its fields (founders, pricing, contact details), to build lists and datasets (companies, people, products, jobs, papers), and for pages that need navigation or interaction to reach the data. Optional effort sets the reasoning budget, maxCredits caps spend, and strictConstrainToURLs keeps the agent to the supplied urls.

This call returns only a job ID, not the research result. Read the job with firecrawl_agent_status until it reaches completed or failed; a typical research run takes one to three minutes. For one known URL use firecrawl_scrape (with formats: ["json"] for structured output); for a plain lookup that a results page answers, use firecrawl_search.

The job also returns a threadId. To continue that thread, pass it with a follow-up prompt; omitted mode, urls, schema and exchange settings carry over from the previous turn.

The agent only calls Alexandria providers whose terms the team has accepted. exchange.skippedProviders lists gated providers. With exchange.onTermsRequired "ask", a terms pendingApproval and exchange.requiresAction carry the approvalId and provider requirements. Read terms/show through firecrawl_scrape. An organization admin must accept terms in the Firecrawl dashboard at the provider URL or https://www.firecrawl.dev/app/settings?tab=data-sources. Ignore any terms/accept call in the API response. Only after the admin confirms acceptance, resume with the same threadId and exchange.approve: {approvalId}; this does not accept terms. To decline, use exchange.decline: {approvalId}. Never infer acceptance from a data request.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>"
    },
    "name": "firecrawl_agent"
  }
}

Input Schema

Name	Required	Description
`mode`	No	"extract" (default) returns the complete structured result every turn. "chat" lets a follow-up that asks no new data get a short reply in message instead of a re-run; required for exchange.requireApproval. Omitted on a follow-up keeps the previous turn's mode.
`urls`	No
`effort`	No	Reasoning budget for the agent task.
`prompt`	Yes
`schema`	No
`exchange`	No	Alexandria provider settings for this turn, forwarded as the request's exchange object.
`threadId`	No	Continue this thread: the threadId from an earlier firecrawl_agent or firecrawl_agent_status result. Omit to start a new thread.
`maxCredits`	No	Spending limit in credits for this run. Defaults to 2500 on the API.
`strictConstrainToURLs`	No	If true, agent will only visit URLs provided in the urls array.

Output Schema

Name	Required	Description
`id`	No	Agent job identifier, for `firecrawl_agent_status`.
`error`	No	Error message or error object when the call did not succeed.
`status`	No	Job state at submission time.
`success`	No	Whether the API call succeeded.
`threadId`	No	Research thread this job belongs to.
`threadTurn`	No	Turn number of this job within its thread.
`agent_hints`	No	Optional response guidance from the Firecrawl API.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.28.2Nov 4, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations only declaring readOnlyHint=false, destructiveHint=false and openWorldHint=true, the description carries real weight and delivers: it discloses the async job-ID-only return, the polling requirement, the threadId continuation semantics with field carry-over, credit spend capping, and the Alexandria provider terms/approval gating flow. It is consistent with (not contradictory to) the non-read-only annotation. It stops short of describing output/result shape, which the output schema covers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: purpose and routing come first, mechanics second, the approval/terms flow last. Every paragraph addresses a distinct concern, but the terms-acceptance section runs long and restates the dashboard URL and 'this does not accept terms' more than once, which dilutes scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nine-parameter tool with a nested `exchange` object, an output schema, and an async multi-turn workflow, the description covers everything an agent needs to call it correctly: what it returns, how to poll, how to resume a thread, and how the terms gate behaves. Return-value details are rightly deferred to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the prose compensates well: it explains the roles of `prompt`, `schema`, `urls`, `effort`, `maxCredits`, `strictConstrainToURLs`, `threadId`, and much of the nested `exchange` object, adding meaning beyond the schema (e.g., omitted settings carry over from the previous turn). The notable gap is `mode` (extract vs chat), a meaningful behavioral switch that the description never discusses despite counting toward the uncovered third of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource ('Run web research that returns structured data') and immediately states the condition that makes it distinct: URLs unknown or the answer spanning several sites. It further enumerates concrete task types (entity+fields, list building, pages needing navigation), so an agent can recognize the job shape without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing guidance is given: use `firecrawl_scrape` with formats ['json'] for one known URL, `firecrawl_search` for a plain results-page lookup, and this tool when URLs are unknown or data spans sites. It also names the required follow-up (`firecrawl_agent_status` until completed/failed) and gives a realistic latency expectation of one to three minutes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.