# Firecrawl MCP Server

> **Firecrawl MCP Server** is a hosted, multitenant Model Context Protocol (MCP) server run by **MewCP** (https://mewcp.com), giving AI agents managed access to Firecrawl.
>
> MewCP takes care of all MCP infrastructure for you — credential storage, OAuth flows,
> token refresh, and production-grade auto-scaling — so your AI agents can connect to
> third-party services and run freely without you managing any MCP server yourself.
>
> To connect your agent to this server you need a MewCP account and your API key:
>   - MEWCP_KEY — your personal API key (dashboard → Developer)
>
> Server page:  https://mewcp.com/mcp/firecrawl
> MewCP docs:   https://docs.mewcp.com
> Full catalog:  https://mewcp.com/llms.txt

## About

Crawl websites and extract clean structured data optimized for AI applications and automation. Collect content from the web at scale while maintaining high-quality outputs.

## How to connect
Server Page URL: https://mewcp.com/mcp/firecrawl
Gateway URL: https://gateway.mewcp.com/personal/mcp

Every request to this server requires one header:
  Authorization: Bearer <MEWCP_KEY>        — your MewCP API key (dashboard → Developer)

All connection snippets and ready-to-use code examples are available on the server page and in this document below. 
---

## Server documentation

**Turn any website into clean, AI-ready data.**

A Model Context Protocol (MCP) server that exposes Firecrawl's API for scraping, crawling, mapping, searching, parsing documents, browser automation, and academic research.


## Overview

The Firecrawl MCP Server provides powerful web data extraction and research capabilities:

- Scrape individual pages or crawl entire websites into markdown, HTML, JSON, and more
- Search the web, map site structures, and run autonomous agent-based data extraction
- Automate browsers with code or natural language, parse documents, and search academic papers and GitHub

Perfect for:

- AI assistants that need to fetch and process live web content
- Automating structured data extraction and research pipelines
- Building competitive intelligence, literature review, and site auditing workflows


## Tools

### Scrape

<details>
<summary><code>scrape_url</code> — Scrape a single URL</summary>

Scrapes a single URL and returns its content in the requested formats. Returns the page as markdown, HTML, screenshot, links, or a summary. For public document URLs (PDF, DOCX) Firecrawl auto-detects and parses them. The response includes `data.metadata.scrapeId` which can be passed to `browser_interact` to continue interacting with the same live browser session.

**Inputs:**
```
- `url` (string, required) — Full URL to scrape, including https://.
- `formats` (list[string], optional, default: ["markdown"]) — Output formats to request: markdown (default), html, rawHtml, links, screenshot, summary, json, audio, video, branding, product, menu. Use ['markdown'] for text content, add 'screenshot' for visual capture.
- `only_main_content` (bool, optional, default: true) — Strip navigation, headers, footers, and ads — keep the article/content body.
- `wait_for` (int, optional, default: 0) — Milliseconds to wait after page load before capturing (0–30000). Use for JS-rendered pages.
- `timeout_ms` (int, optional, default: 30000) — Maximum time the page load may take in milliseconds (1000–300000).
- `mobile` (bool, optional, default: false) — Emulate a mobile viewport.
- `proxy` (string, optional, default: "auto") — Proxy tier: 'auto' (default), 'basic', or 'enhanced' (stealth, higher credit cost).
- `block_ads` (bool, optional, default: true) — Block ads and cookie consent banners before capturing.
- `include_tags` (list[string], optional) — HTML tags to include in output (e.g. ['article', 'main']). Omit to include all.
- `exclude_tags` (list[string], optional) — HTML tags to strip from output (e.g. ['nav', 'footer', 'aside']).
- `remove_base64_images` (bool, optional, default: true) — Drop inline base64 images from markdown output to reduce token usage.
```

**Output `data` schema:**

```typescript
{
  markdown: string | null;
  summary: string | null;
  html: string | null;
  rawHtml: string | null;
  screenshot: string | null;
  links: string[] | null;
  metadata: {
    title: string | null;
    description: string | null;
    language: string | null;
    sourceURL: string | null;
    url: string | null;
    keywords: string | null;
    statusCode: number | null;
    contentType: string | null;
    error: string | null;
    scrapeId: string | null;
  } | null;
  warning: string | null;
}
```

</details>


<details>
<summary><code>batch_scrape_urls</code> — Start a batch scrape job</summary>

Starts an async batch scrape job for a list of URLs. Returns a job ID immediately. Use `get_batch_scrape_status` to poll for completion and retrieve scraped content. Ideal for scraping 5–1000 URLs in parallel without blocking.

**Inputs:**
```
- `urls` (list[string], required) — List of URLs to scrape.
- `formats` (list[string], optional, default: ["markdown"]) — Output formats to request: markdown (default), html, rawHtml, links, screenshot, summary, json, audio, video, branding, product, menu. Use ['markdown'] for text content, add 'screenshot' for visual capture.
- `only_main_content` (bool, optional, default: true) — Strip navigation, headers, footers, and ads from each page.
- `proxy` (string, optional, default: "auto") — Proxy tier: 'auto' (default), 'basic', or 'enhanced' (stealth, higher credit cost).
- `block_ads` (bool, optional, default: true) — Block ads and cookie banners.
- `remove_base64_images` (bool, optional, default: true) — Drop inline base64 images to reduce response size.
- `ignore_invalid_urls` (bool, optional, default: false) — Skip invalid URLs instead of failing the entire job.
- `max_concurrency` (int, optional) — Maximum simultaneous scrapes (leave None for Firecrawl default).
```

**Output `data` schema:**

```typescript
{
  id: string;
  url: string | null;
  invalidURLs: string[] | null;
}
```

</details>


<details>
<summary><code>get_batch_scrape_status</code> — Poll batch scrape status</summary>

Polls the status of a batch scrape job started by `batch_scrape_urls`. Returns status (scraping/completed/failed), progress counters, and scraped pages when done. If `data.next` is present in the response, call again with the same job_id to get the next page of results.

**Inputs:**
```
- `job_id` (string, required) — Batch scrape job ID returned by `batch_scrape_urls`.
```

**Output `data` schema:**

```typescript
{
  status: string;
  total: number | null;
  completed: number | null;
  creditsUsed: number | null;
  expiresAt: string | null;
  next: string | null;
  data: {
    markdown: string | null;
    summary: string | null;
    html: string | null;
    rawHtml: string | null;
    screenshot: string | null;
    links: string[] | null;
    metadata: {
      title: string | null;
      description: string | null;
      language: string | null;
      sourceURL: string | null;
      url: string | null;
      keywords: string | null;
      statusCode: number | null;
      contentType: string | null;
      error: string | null;
      scrapeId: string | null;
    } | null;
    warning: string | null;
  }[] | null;
}
```

</details>


<details>
<summary><code>cancel_batch_scrape</code> — Cancel a batch scrape job</summary>

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Stops a running batch scrape job. All in-progress scraping is terminated and any unfinished results are permanently lost — this cannot be undone. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user exactly which batch scrape job will be cancelled and that unfinished results will be permanently lost, and wait for their explicit written confirmation before proceeding.

**Inputs:**
```
- `job_id` (string, required) — Batch scrape job ID to cancel.
```

**Output `data` schema:**

```typescript
{
  status: string;
}
```

</details>


### Crawl

<details>
<summary><code>crawl_url</code> — Start a full-site crawl</summary>

Starts an async crawl job from a seed URL, following internal links up to the specified depth and page limit. Returns a job ID immediately. Use `get_crawl_status` to poll for progress and results. Use `include_paths`/`exclude_paths` regex patterns to control which URLs are visited. Ideal for extracting all content from a site, documentation, or blog.

**Inputs:**
```
- `url` (string, required) — Seed URL to start crawling from.
- `limit` (int, optional, default: 10000) — Maximum number of pages to crawl (1–10000).
- `max_discovery_depth` (int, optional) — Maximum link depth from the seed URL. Omit for unlimited.
- `include_paths` (list[string], optional) — Regex patterns — only URLs matching at least one pattern are crawled.
- `exclude_paths` (list[string], optional) — Regex patterns — URLs matching any pattern are skipped.
- `sitemap` (string, optional, default: "include") — Sitemap usage: 'include' (use sitemap + crawl), 'skip' (crawl only), 'only' (sitemap only).
- `allow_subdomains` (bool, optional, default: false) — Follow links to subdomains of the seed URL.
- `allow_external_links` (bool, optional, default: false) — Follow links to entirely different domains.
- `ignore_query_parameters` (bool, optional, default: false) — Treat URLs that differ only in query parameters as duplicates.
- `formats` (list[string], optional, default: ["markdown"]) — Output formats to request: markdown (default), html, rawHtml, links, screenshot, summary, json, audio, video, branding, product, menu. Use ['markdown'] for text content, add 'screenshot' for visual capture.
- `only_main_content` (bool, optional, default: true) — Strip navigation, headers, footers, and ads from each page.
- `proxy` (string, optional, default: "auto") — Proxy tier: 'auto' (default), 'basic', or 'enhanced' (stealth, higher credit cost).
- `block_ads` (bool, optional, default: true) — Block ads and cookie banners.
```

**Output `data` schema:**

```typescript
{
  id: string;
  url: string | null;
}
```

</details>


<details>
<summary><code>get_crawl_status</code> — Poll crawl status</summary>

Polls the status of a crawl job started by `crawl_url`. Returns status (scraping/completed/failed/cancelled), progress counters, and crawled pages. If `data.next` is present, call again to retrieve the next page of results.

**Inputs:**
```
- `job_id` (string, required) — Crawl job ID returned by `crawl_url`.
```

**Output `data` schema:**

```typescript
{
  status: string;
  total: number | null;
  completed: number | null;
  creditsUsed: number | null;
  expiresAt: string | null;
  createdAt: string | null;
  completedAt: string | null;
  duration: number | null;
  next: string | null;
  data: {
    markdown: string | null;
    summary: string | null;
    html: string | null;
    rawHtml: string | null;
    screenshot: string | null;
    links: string[] | null;
    metadata: {
      title: string | null;
      description: string | null;
      language: string | null;
      sourceURL: string | null;
      url: string | null;
      keywords: string | null;
      statusCode: number | null;
      contentType: string | null;
      error: string | null;
      scrapeId: string | null;
    } | null;
    warning: string | null;
  }[] | null;
}
```

</details>


<details>
<summary><code>cancel_crawl</code> — Cancel a crawl job</summary>

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Stops a running crawl job. All in-progress crawling is terminated and any unfinished pages are permanently lost — this cannot be undone. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user which crawl job will be cancelled and that unfinished pages will be permanently lost, and wait for their explicit written confirmation before proceeding.

**Inputs:**
```
- `job_id` (string, required) — Crawl job ID to cancel.
```

**Output `data` schema:**

```typescript
{
  status: string;
}
```

</details>


### Discover

<details>
<summary><code>map_url</code> — Map all URLs on a website</summary>

Discovers all URLs on a website without scraping their content. Returns a list of links with title and description. Use before `crawl_url` to understand site structure, or pass `search` to filter URLs by relevance to a topic. Much faster and cheaper than crawling when you only need the URL list.

**Inputs:**
```
- `url` (string, required) — Root URL of the site to map.
- `search` (string, optional) — Filter and rank URLs by relevance to this search query.
- `sitemap` (string, optional, default: "include") — 'include' (sitemap + crawl), 'skip' (crawl only), 'only' (sitemap only).
- `include_subdomains` (bool, optional, default: true) — Include URLs from subdomains of the root URL.
- `ignore_query_parameters` (bool, optional, default: true) — Deduplicate URLs that differ only in query parameters.
- `ignore_cache` (bool, optional, default: false) — Bypass sitemap cache to get the freshest URL list.
- `limit` (int, optional, default: 5000) — Maximum number of URLs to return (1–100000).
- `country` (string, optional) — ISO 3166-1 alpha-2 country code for geo-targeting (e.g. 'US', 'DE').
```

**Output `data` schema:**

```typescript
{
  links: {
    url: string;
    title: string | null;
    description: string | null;
  }[];
}
```

</details>


<details>
<summary><code>search_web</code> — Search the web</summary>

Searches the web and optionally scrapes the full content of each result. Returns web pages, images, or news depending on `sources`. Set `scrape_formats` to ['markdown'] to get full page content alongside each result — omit to get only title, description, and URL. Supports operator syntax: site:, filetype:, intitle:, -exclude, "exact phrase".

**Inputs:**
```
- `query` (string, required) — Search query. Supports operators: site:domain.com, filetype:pdf, intitle:keyword, -exclude, "exact phrase", related:domain.com.
- `limit` (int, optional, default: 10) — Number of results to return (1–100).
- `sources` (list[string], optional, default: ["web"]) — Result types to return: 'web', 'images', 'news'. Combine as needed.
- `categories` (list[string], optional) — Filter to specific result categories: 'github', 'research', 'pdf'.
- `country` (string, optional) — ISO country code for geo-targeted results (e.g. 'US', 'DE', 'JP'). Default: US.
- `location` (string, optional) — City/region for geo-targeted results (e.g. 'San Francisco,California,United States').
- `tbs` (string, optional) — Time-based filter: 'qdr:d' (past day), 'qdr:w' (past week), 'qdr:m' (past month).
- `include_domains` (list[string], optional) — Restrict results to these domains (mutually exclusive with exclude_domains).
- `exclude_domains` (list[string], optional) — Remove these domains from results (mutually exclusive with include_domains).
- `scrape_formats` (list[string], optional) — If provided, each result page is scraped and content returned in these formats. Omit to return only title/description/URL without scraping.
- `timeout_ms` (int, optional, default: 45000) — Request timeout in milliseconds (1000–300000). Default 45000.
```

**Output `data` schema:**

```typescript
{
  results: {
    web: {
      title: string | null;
      description: string | null;
      url: string | null;
      markdown: string | null;
      html: string | null;
      rawHtml: string | null;
      category: string | null;
    }[] | null;
    images: {
      title: string | null;
      imageUrl: string | null;
      imageWidth: number | null;
      imageHeight: number | null;
      url: string | null;
      position: number | null;
    }[] | null;
    news: {
      title: string | null;
      snippet: string | null;
      url: string | null;
      date: string | null;
      imageUrl: string | null;
      position: number | null;
      markdown: string | null;
    }[] | null;
  } | null;
  warning: string | null;
  id: string | null;
  creditsUsed: number | null;
}
```

</details>


### Parse

<details>
<summary><code>parse_document</code> — Parse a document file</summary>

Parses a local or private document (PDF, DOCX, XLSX, HTML, and more) into clean markdown or structured data. Use when the file is not publicly accessible by URL — for public URLs use `scrape_url` instead. The file must be provided as base64-encoded bytes, making this suitable for workflow chains where a previous step fetches and encodes the file content.

**Inputs:**
```
- `file_content_b64` (string, required) — Base64-encoded file bytes to parse.
- `file_name` (string, required) — Filename including extension (e.g. 'report.pdf', 'data.docx'). Extension determines parser.
- `formats` (list[string], optional, default: ["markdown"]) — Output formats: markdown, html, rawHtml, links, summary.
- `only_main_content` (bool, optional, default: true) — Strip headers, footers, and decorative content.
```

**Output `data` schema:**

```typescript
{
  markdown: string | null;
  summary: string | null;
  html: string | null;
  rawHtml: string | null;
  links: string[] | null;
  metadata: {
    title: string | null;
    description: string | null;
    language: string | null;
    sourceURL: string | null;
    url: string | null;
    keywords: string | null;
    statusCode: number | null;
    contentType: string | null;
    error: string | null;
    scrapeId: string | null;
  } | null;
  warning: string | null;
}
```

</details>


### Agent

<details>
<summary><code>run_agent</code> — Start an autonomous data extraction agent</summary>

Starts an autonomous web research agent that searches, navigates, and extracts data based on a natural language prompt. No URLs required — the agent finds them. Use `schema` to get structured JSON output. Returns a job ID; use `get_agent_status` to poll. Use `spark-1-mini` (default, 60% cheaper) for most tasks; `spark-1-pro` for complex multi-domain research. Set `max_credits` to cap spending — the job fails without charges if the limit is hit.

**Inputs:**
```
- `prompt` (string, required) — Natural language description of the data to find (max 10000 chars). Be specific: 'Find the 5 most-funded AI startups in 2024 with founder names and total funding.'
- `urls` (list[string], optional) — Optional seed URLs to focus the agent. Omit to let the agent search freely.
- `schema` (string, optional) — JSON schema string for structured output. Omit for free-form text.
- `model` (string, optional, default: "spark-1-mini") — 'spark-1-mini' (default, cheaper) or 'spark-1-pro' (higher accuracy).
- `max_credits` (int, optional) — Credit cap for this job (default 2500). Job fails without charges if exceeded.
```

**Output `data` schema:**

```typescript
{
  id: string | null;
  status: string | null;
  data: object | null;
  expiresAt: string | null;
  creditsUsed: number | null;
}
```

</details>


<details>
<summary><code>get_agent_status</code> — Poll agent job status</summary>

Polls the status of an agent job started by `run_agent`. Returns status (processing/completed/failed/cancelled), extracted data when done, and credit usage. Poll every 15–30 seconds; jobs typically complete in 1–5 minutes.

**Inputs:**
```
- `job_id` (string, required) — Agent job ID returned by `run_agent`.
```

**Output `data` schema:**

```typescript
{
  id: string | null;
  status: string | null;
  data: object | null;   // shape matches the schema passed to run_agent
  expiresAt: string | null;
  creditsUsed: number | null;
}
```

</details>


<details>
<summary><code>cancel_agent</code> — Cancel an agent job</summary>

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Requests cancellation of a running agent job. Any in-progress reasoning steps complete before the job transitions to cancelled — credits for completed steps may still be charged and cannot be recovered. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user which agent job will be cancelled and the credit implications, and wait for their explicit written confirmation before proceeding.

**Inputs:**
```
- `job_id` (string, required) — Agent job ID to cancel.
```

**Output `data` schema:**

```typescript
{
  status: string;
}
```

</details>


### Browser

<details>
<summary><code>browser_interact</code> — Interact with a browser session</summary>

Executes code or a natural language prompt in the live browser session bound to a previous scrape job. The `scrape_id` comes from `data.metadata.scrapeId` in a `scrape_url` response. First call creates the browser session at the same page state as the scrape. Subsequent calls on the same `scrape_id` reuse the live session. Provide either `code` (Playwright/Node/Python/Bash to run) or `prompt_text` (AI-driven navigation), not both. Returns CDP URL, live view URL, stdout, and AI output. Call `browser_close` when done to release the session.

**Inputs:**
```
- `scrape_id` (string, required) — Scrape job ID from `data.metadata.scrapeId` in a `scrape_url` response.
- `code` (string, optional) — Code to execute in the browser sandbox (1–100000 chars). Provide this OR prompt_text, not both.
- `prompt_text` (string, optional) — Natural language task for the AI browser agent (1–10000 chars). Provide this OR code, not both.
- `language` (string, optional, default: "node") — Code language when using `code`: 'node' (default), 'python', or 'bash'.
- `timeout` (int, optional, default: 30) — Execution timeout in seconds (1–300).
```

**Output `data` schema:**

```typescript
{
  cdpUrl: string | null;
  liveViewUrl: string | null;
  interactiveLiveViewUrl: string | null;
  output: string | null;      // AI response when using prompt_text
  stdout: string | null;
  result: string | null;
  stderr: string | null;
  exitCode: number | null;
  killed: boolean | null;
}
```

</details>


<details>
<summary><code>browser_close</code> — Close a browser session</summary>

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Destroys the browser session attached to a scrape job. All browser state, cookies, and session data are permanently lost and the session cannot be resumed — this cannot be undone. Always call this when done interacting to avoid leaking browser resources and credits. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, confirm with the user that the browser session is no longer needed, and wait for their explicit written confirmation before proceeding.

**Inputs:**
```
- `scrape_id` (string, required) — Scrape job ID whose browser session to close (same ID used in browser_interact).
```

**Output `data` schema:**

```typescript
{
  status: string;
}
```

</details>


### Research

<details>
<summary><code>search_papers</code> — Search academic research papers</summary>

Searches Firecrawl's academic research index by topic, method, benchmark, or author. Returns ranked papers with paperId, title, abstract, and relevance score. Use `paperId` from results to call `get_paper` or `find_related_papers`. Supports filtering by author name substring, category (e.g. 'cs.LG'), and date range.

**Inputs:**
```
- `query` (string, required) — Natural language search query (e.g. 'diffusion models image synthesis').
- `k` (int, optional, default: 40) — Maximum number of ranked papers to return (1–500).
- `authors` (string, optional) — Filter by author name substring (e.g. 'LeCun'). Comma-separate for multiple.
- `categories` (string, optional) — Filter by paper category (e.g. 'cs.LG', 'cs.CV'). Comma-separate for multiple.
- `from_date` (string, optional) — Inclusive lower bound on paper date in YYYY-MM-DD format (e.g. '2023-01-01').
- `to_date` (string, optional) — Inclusive upper bound on paper date in YYYY-MM-DD format.
```

**Output `data` schema:**

```typescript
{
  results: {
    paperId: string | null;
    primaryId: string | null;
    ids: { arxiv: string[] | null; } | null;
    title: string | null;
    abstract: string | null;
    score: number | null;
  }[];
}
```

</details>


<details>
<summary><code>get_paper</code> — Get full details for a research paper</summary>

Retrieves full details for a specific research paper by its ID. Returns title, abstract, authors, categories, and dates. The `paper_id` can be a canonical paperId (e.g. '2014215642691656232') or a source-prefixed ID (e.g. 'arxiv:2105.05233') from `search_papers` results.

**Inputs:**
```
- `paper_id` (string, required) — Paper ID — either canonical paperId or source-prefixed ID like 'arxiv:2105.05233'.
- `k` (int, optional) — Number of related papers to include alongside the paper details.
```

**Output `data` schema:**

```typescript
{
  paper: {
    paperId: string | null;
    primaryId: string | null;
    ids: { arxiv: string[] | null; } | null;
    title: string | null;
    abstract: string | null;
    authors: string | null;
    categories: string[] | null;
    createdDate: string | null;
    updateDate: string | null;
  };
}
```

</details>


<details>
<summary><code>find_related_papers</code> — Find papers related to a seed paper</summary>

Finds papers related to a seed paper, ranked by semantic relevance to an intent. Use `mode` to choose expansion strategy: 'similar' (semantically close), 'citers' (papers that cite the seed), 'references' (papers cited by the seed). Returns ranked results with relevance scores. Ideal for literature review workflows: search_papers → find_related_papers → get_paper.

**Inputs:**
```
- `paper_id` (string, required) — Seed paper ID (canonical paperId or 'arxiv:XXXX.XXXXX').
- `intent` (string, required) — Natural language ranking intent (e.g. 'applications in medical imaging').
- `mode` (string, optional, default: "similar") — Expansion mode: 'similar' (default), 'citers', or 'references'.
- `k` (int, optional, default: 40) — Maximum number of related papers to return (1–500).
- `rerank` (bool, optional, default: false) — Apply an additional reranking pass over the fused candidate set.
```

**Output `data` schema:**

```typescript
{
  results: {
    paperId: string | null;
    primaryId: string | null;
    title: string | null;
    abstract: string | null;
    score: number | null;
  }[];
  poolSize: number | null;
  truncated: boolean | null;
}
```

</details>


<details>
<summary><code>search_github</code> — Search GitHub issues, PRs, and repos</summary>

Searches GitHub issue history, pull requests, discussions, and repository READMEs using natural language. Returns matched content with repository metadata, URLs, and markdown snippets. Useful for researching how a bug was fixed, what a library's maintainers have said, or finding prior art in open source projects.

**Inputs:**
```
- `query` (string, required) — Natural language query (e.g. 'race condition in worker shutdown firecrawl').
- `k` (int, optional, default: 20) — Maximum number of results to return (1–100).
```

**Output `data` schema:**

```typescript
{
  results: {
    resultType: string | null;   // issue | pull_request | repository | discussion
    repo: string | null;
    url: string | null;
    pageType: string | null;
    number: number | null;
    title: string | null;
    snippet: string | null;
    contentMd: string | null;
  }[];
}
```

</details>


## API Parameters Reference

<details>
<summary><strong>Response Envelope</strong></summary>

Every tool returns the same top-level envelope. Only `data` varies per tool.

```typescript
// Success
{
  success: true;
  statusCode: number;
  retriable: false;
  retry_after_seconds: null;
  error: null;
  data: { ... };   // schema shown per tool above
}

// Error
{
  success: false;
  statusCode: number;
  retriable: boolean;
  retry_after_seconds: number | null;
  error: {
    code: string;    // VALIDATION_ERROR | AUTH_ERROR | UPSTREAM_ERROR | SERVER_ERROR
    message: string;
    details: object;
  };
  data: null;
}
```

- `retriable` — `true` when it is safe to retry (rate limit, network error, 503). `false` for validation and auth errors.
- `retry_after_seconds` — seconds to wait before retrying; present only when `retriable` is `true` and the upstream specifies a delay.
- `error.code` — machine-readable string: `VALIDATION_ERROR`, `AUTH_ERROR`, `UPSTREAM_ERROR`, `SERVER_ERROR`.

</details>

<details>
<summary><strong>Output Formats</strong></summary>

All scraping tools accept a `formats` list:

- `markdown` — Clean markdown (default)
- `html` — Cleaned HTML
- `rawHtml` — Raw page HTML
- `screenshot` — Page screenshot as base64
- `links` — All links found on the page
- `summary` — AI-generated page summary
- `json` — Structured JSON extraction
- `audio`, `video`, `branding`, `product`, `menu` — Specialised extraction modes

</details>

<details>
<summary><strong>Proxy Options</strong></summary>

- `auto` — Automatically selects the best proxy (default)
- `basic` — Standard proxy for general use
- `enhanced` — Stealth proxy for bot-protected sites (higher credit cost)

</details>

<details>
<summary><strong>Async Job Workflow</strong></summary>

`batch_scrape_urls`, `crawl_url`, and `run_agent` are asynchronous — they return a job ID immediately:

1. Call the tool → receive `data.id`
2. Poll the matching status tool (`get_batch_scrape_status`, `get_crawl_status`, `get_agent_status`) with the job ID
3. Keep polling until `status` is `completed`, `failed`, or `cancelled`
4. If `data.next` is present in the status response, call again with the same job ID to page through results

**Recommended polling interval:** every 15–30 seconds. Allow at least 2–3 minutes for crawl and agent jobs.

</details>

<details>
<summary><strong>Time-Based Search Filters (tbs)</strong></summary>

Use the `tbs` parameter in `search_web` to filter results by recency:

```
qdr:h  — Past hour
qdr:d  — Past day
qdr:w  — Past week
qdr:m  — Past month
qdr:y  — Past year
```

</details>

<details>
<summary><strong>Research Paper IDs</strong></summary>

`get_paper` and `find_related_papers` accept two ID formats:

```
Canonical:        2014215642691656232
Source-prefixed:  arxiv:2105.05233
```

Use `paperId` or `primaryId` from `search_papers` results.

</details>


## Getting Your Firecrawl API Key

<details>
<summary><strong>Steps</strong></summary>

1. Go to [Firecrawl](https://www.firecrawl.dev) and sign in or create an account
2. Navigate to **API Keys** in your dashboard
3. Click **Create API Key**
4. Copy the generated key — you will only see it once

</details>


## Troubleshooting

<details>
<summary><strong>Missing or Invalid Headers</strong></summary>

- **Cause:** API key not provided in request headers or incorrect format
- **Solution:**
  1. Verify `Authorization: Bearer YOUR_API_KEY` and `X-Mewcp-Credential-Id: CREDENTIAL-ID` headers are present
  2. Check API key is active in your MewCP account

</details>

<details>
<summary><strong>Insufficient Credits</strong></summary>

- **Cause:** API calls have exceeded your request limits
- **Solution:**
  1. Check credit usage in your Curious Layer dashboard
  2. Upgrade to a paid plan or add credits for higher limits
  3. Contact support for credit adjustments

</details>

<details>
<summary><strong>Credential Not Connected</strong></summary>

- **Cause:** No Firecrawl credential linked to your account
- **Solution:**
  1. Go to **Credentials** in your MewCP dashboard
  2. Add your Firecrawl API key
  3. Retry the request with the correct `X-Mewcp-Credential-Id` header

</details>

<details>
<summary><strong>Malformed Request Payload</strong></summary>

- **Cause:** JSON payload is invalid or missing required fields
- **Solution:**
  1. Validate JSON syntax before sending
  2. Ensure all required tool parameters are included
  3. Check parameter types match expected values (e.g. `timeout_ms` must be 1000–300000)

</details>

<details>
<summary><strong>Server Not Found</strong></summary>

- **Cause:** Incorrect server name in the API endpoint
- **Solution:**
  1. Verify endpoint format: `{server-name}/mcp/{tool-name}`
  2. Use the correct server name from documentation
  3. Check available servers in your Curious Layer account

</details>

<details>
<summary><strong>Firecrawl API Error</strong></summary>

- **Cause:** Upstream Firecrawl API returned an error
- **Solution:**
  1. Check Firecrawl service status at [Firecrawl Status](https://www.firecrawl.dev)
  2. Verify your API key has sufficient credits for the operation
  3. Review the error message in the response for specific details

</details>

---

<details>
<summary><strong>Resources</strong></summary>

- **[Firecrawl Documentation](https://docs.firecrawl.dev)** — Official API reference
- **[Firecrawl API Reference](https://docs.firecrawl.dev/api-reference)** — Complete endpoint reference
- **[FastMCP Docs](https://gofastmcp.com/v2/getting-started/welcome)** — FastMCP specification
- **[FastMCP Credentials](https://pypi.org/project/fastmcp-credentials/)** — FastMCP Credentials package for credential handling

</details>


---

## Connection snippets

### Python (fastmcp)

```python
import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

SERVER_URL = "https://gateway.mewcp.com/personal/mcp"
MEWCP_KEY = "YOUR_MEWCP_KEY"

transport = StreamableHttpTransport(
    url=SERVER_URL,
    headers={
        "Authorization": f"Bearer {MEWCP_KEY}",
    }
)

async def main():
    client = Client(transport)

    async with client:
        await client.ping()
        tools = await client.list_tools()
        resources = await client.list_resources()
        prompts = await client.list_prompts()
        # Change the tool name and arguments with actual tool and arguments available in server
        result = await client.call_tool("example_tool", {"param": "value"})
        print(result)

asyncio.run(main())
```

### TypeScript (MCP SDK)

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const SERVER_URL = "https://gateway.mewcp.com/personal/mcp";
const MEWCP_KEY = "YOUR_MEWCP_KEY";

const transport = new StreamableHTTPClientTransport(new URL(SERVER_URL), {
  requestInit: {
    headers: {
      Authorization: `Bearer ${MEWCP_KEY}`,
    },
  },
});

const client = new Client({
  name: "mewcp-client",
  version: "1.0.0",
});

await client.connect(transport);

const tools = await client.listTools();
console.log("Available tools:", tools.tools.map(t => t.name));

// Change the tool name and arguments to a tool available on your server
const result = await client.callTool({
  name: "example_tool",
  arguments: { param: "value" },
});

console.log("Tool result:", result);
```

### VS Code (settings.json)

```json
{
  "servers": {
    "mewcp": {
      "type": "http",
      "url": "https://gateway.mewcp.com/personal/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MEWCP_KEY"
      }
    }
  }
}
```

### Cursor (mcp.json)

```json
{
  "mcpServers": {
    "mewcp": {
      "url": "https://gateway.mewcp.com/personal/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MEWCP_KEY"
      }
    }
  }
}
```

### Claude Desktop (claude_desktop_config.json)

```json

  "mcpServers": {
    "mewcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://gateway.mewcp.com/personal/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer YOUR_MEWCP_KEY"
      ]
    }
  }

```