Skip to main content
Glama
Sign In
Firecrawl MCP Server

Firecrawl MCP Server

by firecrawl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Firecrawl agent

firecrawl_agent

Run multi-site web research to return structured JSON when source URLs are unknown; submit a prompt and optional schema, then poll the job status for results.

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.

Input Schema

NameRequiredDescriptionDefault
modeNo"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.
urlsNo
effortNoReasoning budget for the agent task.
promptYes
schemaNo
exchangeNoAlexandria provider settings for this turn, forwarded as the request's exchange object.
threadIdNoContinue this thread: the threadId from an earlier firecrawl_agent or firecrawl_agent_status result. Omit to start a new thread.
maxCreditsNoSpending limit in credits for this run. Defaults to 2500 on the API.
strictConstrainToURLsNoIf true, agent will only visit URLs provided in the urls array.

Output Schema

NameRequiredDescriptionDefault
idNoAgent job identifier, for `firecrawl_agent_status`.
errorNoError message or error object when the call did not succeed.
statusNoJob state at submission time.
successNoWhether the API call succeeded.
threadIdNoResearch thread this job belongs to.
threadTurnNoTurn number of this job within its thread.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.36.1
    • changedInput schema / properties / schema / additionalProperties
      Previous value: -{}New value: +true
  2. Changed8 schema fields changedv1.0.2
    • changedInput schema / $schema
      Previous value: -"https://json-schema.org/draft/2020-12/schema"New value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / properties / effort
      Added value: +{
+  "description": "Reasoning budget for the agent task.",
+  "enum": [
+    "low",
+    "medium",
+    "high"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / exchange
      Added value: +{
+  "additionalProperties": false,
+  "description": "Alexandria provider settings for this turn, forwarded as the request's exchange object.",
+  "properties": {
+    "approve": {
+      "additionalProperties": false,
+      "description": "Answer yes to the pendingApproval the previous turn of this thread ended on (its id, also exchange.requiresAction.approvalId). Needs threadId. For a terms offer, send it only after an organization admin confirms acceptance in the Firecrawl dashboard; this does not accept terms. callIds and always are ignored on terms offers. For paid calls, callIds picks a subset (default all) and always stops asking for the rest of the thread.",
+      "properties": {
+        "always": {
+          "type": "boolean"
+        },
+        "approvalId": {
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+          "type": "string"
+        },
+        "callIds": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "approvalId"
+      ],
+      "type": "object"
+    },
+    "decline": {
+      "additionalProperties": false,
+      "description": "Answer no to that pendingApproval. Needs threadId. A declined terms offer keeps those providers out of the rest of the thread.",
+      "properties": {
+        "approvalId": {
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+          "type": "string"
+        }
+      },
+      "required": [
+        "approvalId"
+      ],
+      "type": "object"
+    },
+    "enabled": {
+      "description": "Let the agent call Alexandria providers. On by default.",
+      "type": "boolean"
+    },
+    "maxCalls": {
+      "description": "Most provider calls the agent may make in this turn.",
+      "maximum": 30,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "onTermsRequired": {
+      "description": "What to do when a provider the agent would use needs data terms the team has not accepted. Gated providers are never called. \"skip\" (default): answer with accepted providers and list the rest in exchange.skippedProviders. \"ask\": the same, plus a terms pendingApproval and exchange.requiresAction. Read terms with terms/show; an organization admin accepts them in the Firecrawl dashboard. There is no auto-accept. Omitted on a follow-up keeps the previous turn's value.",
+      "enum": [
+        "skip",
+        "ask"
+      ],
+      "type": "string"
+    },
+    "requireApproval": {
+      "description": "End the turn with a paid-call pendingApproval before any paid provider call. Requires mode \"chat\" on the same request, even on a follow-up.",
+      "type": "boolean"
+    },
+    "toolkits": {
+      "description": "Pin up to 5 providers the agent may use, by slug. Omitted means the whole catalog.",
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 5,
+      "type": "array"
+    }
+  },
+  "type": "object"
+}
    • addedInput schema / properties / maxCredits
      Added value: +{
+  "description": "Spending limit in credits for this run. Defaults to 2500 on the API.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}
    • addedInput schema / properties / mode
      Added value: +{
+  "description": "\"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.",
+  "enum": [
+    "extract",
+    "chat"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / strictConstrainToURLs
      Added value: +{
+  "description": "If true, agent will only visit URLs provided in the urls array.",
+  "type": "boolean"
+}
    • addedInput schema / properties / threadId
      Added value: +{
+  "description": "Continue this thread: the threadId from an earlier firecrawl_agent or firecrawl_agent_status result. Omit to start a new thread.",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "description": "The queued research job. The result is read with `firecrawl_agent_status`.",
+  "properties": {
+    "error": {
+      "description": "Error message or error object when the call did not succeed."
+    },
+    "id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Agent job identifier, for `firecrawl_agent_status`."
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Job state at submission time."
+    },
+    "success": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Whether the API call succeeded."
+    },
+    "threadId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Research thread this job belongs to."
+    },
+    "threadTurn": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Turn number of this job within its thread."
+    }
+  },
+  "type": "object"
+}
  3. First observedv1.0.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare only readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the description carries real weight and does: it discloses that this call returns only a job ID, that the agent must poll firecrawl_agent_status until completed/failed, and that a run typically takes one to three minutes. It adds cost semantics (maxCredits caps spend), thread continuation with inherited settings, and the full gated-provider/terms approval path including skippedProviders and approve/decline — none of which is inferable from the annotations.

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 the sibling routing come first, then the async/thread mechanics, then terms handling. The terms paragraph is dense and partially restates schema descriptions for exchange.approve and onTermsRequired, and the dashboard URL is verbose, but given a 9-parameter async tool with nested exchange objects most of the length earns its place.

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?

An output schema exists, so return-value shape need not be explained, yet the description still supplies the critical lifecycle fact that the response is a job ID to be polled. Combined with cost limits, thread continuation, and the terms-approval resumption protocol, an agent has everything needed to call this correctly and to recover from a pendingApproval.

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?

Given 9 parameters at 67% schema coverage, the description compensates well: it explains prompt as the field description, schema as optional JSON output shape, urls as seeds, effort as reasoning budget, maxCredits as spend cap, strictConstrainToURLs as a hard constraint, and threadId as thread continuation with settings carry-over. It also walks through exchange.approve/decline and exchange.onTermsRequired behavior. Minor gap: the mode extract-vs-chat distinction and exchange.toolkits/maxCalls are only lightly touched.

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 gives a specific verb and resource ("Run web research") plus the exact conditions that select this tool: URLs unknown or answer spans several sites, returning JSON assembled across sources. It also names what this tool is not, contrasting it with firecrawl_scrape for one known URL and firecrawl_search for a plain lookup, so an agent can disambiguate among 27 siblings without opening a schema.

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

Usage Guidelines4/5

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

The description gives concrete use cases (research an entity plus fields, build lists/datasets, pages needing navigation) and explicitly routes competing cases to firecrawl_scrape and firecrawl_search. It also states the follow-up protocol (continue a thread via threadId) and the terms/approval workflow. It stops short of an explicit "do not use this when..." exclusion beyond the sibling routing.

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

Deploy Server

Other Tools