firecrawl / firecrawl/firecrawl-mcp-server
README: keyless tool list and `formats` object syntax both disagree with v3.23.3 behavior
- 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