firecrawl / firecrawl/firecrawl-mcp-server

README: keyless tool list and `formats` object syntax both disagree with v3.23.3 behavior

Open
#357 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
7.5k
Forks
884
Avg merge
1d 11h
Merged PRs (30d)
14

Description

Two spots in `README.md` on `main` describe behavior that the current code does not implement. Both were hit while setting up the hosted endpoint, and both cost some debugging time, so filing them together.

Verified against `https://mcp.firecrawl.dev/v2/mcp` on 2026-08-06, which reports `serverInfo: {"name":"firecrawl-fastmcp","version":"3.23.3"}` — the same version as `package.json` on `main`, so this is not a stale deployment.

---

### 1. Keyless tool list says `interact`, but the endpoint serves `parse`

README:

> On the keyless free tier, `scrape`, `search`, and `interact` work without an API key (rate-limited).

Actual `tools/list` on the keyless endpoint returns three tools:

```
firecrawl_scrape
firecrawl_search
firecrawl_parse
```

The server's own `initialize` instructions agree with the wire behavior and not with the README:

> Without authentication, this endpoint exposes Search, Scrape, and Parse with usage limits.

This looks like the README simply wasn't updated when parse gained keyless support — the CHANGELOG entry for `firecrawl_parse` on the hosted server notes "the flow also works on the keyless remote URL".

---

### 2. `formats` does not accept the documented object form

The README's preferred scrape example passes an object inside `formats`:

```json
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com/product",
"formats": [
{
"type": "json",
"prompt": "Extract the product information",
"schema": { "...": "..." }
}
]
}
}
```

That request is rejected:

```
MCP error -32602: Tool 'firecrawl_scrape' parameter validation failed: formats.0:
Invalid option: expected one of "markdown"|"html"|"rawHtml"|"screenshot"|"links"|
"summary"|"changeTracking"|"branding"|"json"|"query"|"audio".
```

`src/index.ts` confirms `formats` is an enum of plain strings, and that the object form is built internally from a sibling `jsonOptions` argument:

```ts
if (fmt === 'json') {
const jsonOpts = args.jsonOptions as Record | undefined;
result.push({ type: 'json', ...jsonOpts });
```

So the shape that actually works is:

```json
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com/product",
"formats": ["json"],
"jsonOptions": {
"prompt": "Extract the product information",
"schema": { "...": "..." }
}
}
}
```

Confirmed working against the keyless endpoint.

The same object-in-`formats` pattern appears in several other README examples (the branding example, the `firecrawl_search` `scrapeOptions` block), so a fix probably wants a sweep rather than a single edit.

Worth noting this one is the more expensive of the two: the README presents the JSON format as the recommended default to avoid context overflow, so it is the first thing a new user copies, and the `-32602` message does not hint that `jsonOptions` is where those fields belong.

---

### Suggested fix

1. Change the keyless sentence to `scrape`, `search`, and `parse`, and drop `interact` from that list (it stays in the key-required set alongside `crawl`, `map`, `agent`, `extract`).
2. Rewrite the `formats` examples to the `formats: ["json"] + jsonOptions` shape.

Happy to open a PR for the README if that's useful.

Contributor guide

No contributing guide indexed for this repository

Research direction

Read README.md alongside src/index.ts, starting with the keyless tool description and the scrape formats handling. Sweep the README examples that use object values inside formats and compare them with the formats and jsonOptions shape shown by src/index.ts. Done means the keyless list says parse instead of interact and all affected examples match the working request syntax.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.