Skip to content

search-profile.md

Latest commit

 

History

History
82 lines (65 loc) · 4.05 KB

search-profile.md

File metadata and controls

82 lines (65 loc) · 4.05 KB
Raw

Search-only MCP surface (/v2/mcp-search)

The server runs two FastMCP instances in one process:

  • The full surface at /v2/mcp, with the complete tool set unchanged.
  • The search surface at /v2/mcp-search, with a fixed, read-only subset.

Only the request path selects the surface. There is no inspection of client identity, User-Agent, or clientInfo.

Tool contract

The search surface exposes exactly these six read-only tools and nothing else:

Tool Purpose
firecrawl_search Ranked web / index search results
firecrawl_research_search_papers Semantic search over indexed research papers
firecrawl_research_inspect_paper Canonical metadata for one paper
firecrawl_research_related_papers Citation-graph expansion from anchor papers
firecrawl_research_read_paper Full-text passages from one paper
firecrawl_research_search_github Search public repository history and readmes

Registration on this instance is filtered against that allowlist, so any tool outside the set, including scrape, map, crawl, extract, agent, interact, parse, monitor, and the feedback tools, is never registered. Both tools/list and tools/call reflect only the six tools; calling anything else returns an unknown-tool error.

No page-content fetching

The search surface's firecrawl_search takes no scrapeOptions. Its input schema is strict (unknown fields are rejected), and its executor builds the outbound /v2/search body from an explicit list of allowed fields (query, limit, tbs, filter, location, sources, categories, highlights, enterprise) plus origin. It never spreads raw arguments, so no request from this surface can ask the API to fetch third-party page content. The schema and body construction enforce this directly, and contract tests guard the behavior. No runtime filter is involved.

OAuth

  • Resource identity. The surface advertises its own protected resource, https://mcp.firecrawl.dev/v2/mcp-search, distinct from the full surface's https://mcp.firecrawl.dev/v2/mcp.
  • Path-scoped metadata (RFC 9728). The protected-resource metadata document is served at /.well-known/oauth-protected-resource/v2/mcp-search. The 401 challenge's WWW-Authenticate: ... resource_metadata=... points at that document.
  • Authenticated discovery. Every request, including tools/list, requires a credential; the keyless free-tier fallback does not apply here.
  • Audience enforcement. OAuth access tokens are introspected and must be bound to this exact resource: a token whose audience names a different resource, or that carries no audience binding at all, is rejected with a 401 (fail closed). Plain API keys carry no audience and are a direct credential, so they are unaffected.

The full surface's OAuth behavior is unchanged (origin-level metadata, no audience enforcement, keyless fallback intact).

Deployment

Both instances start from the same image and process. The in-pod reverse proxy routes /v2/mcp-search (and its key-in-path form /{apiKey}/v2/mcp-search) plus the metadata path to the search instance's local port; everything else routes to the full instance as before. If the search instance fails to bind its port, it is logged and skipped; the full instance is unaffected. No new domain and no infrastructure changes are required.

The bundled hosted deployment fixes the public path at /v2/mcp-search, the internal search port at 3001, and the OAuth resource at https://mcp.firecrawl.dev/v2/mcp-search. FIRECRAWL_MCP_SEARCH_ENABLED is the supported operational toggle. Node-level overrides for the port, endpoint, and resource exist for isolated tests only; they do not update docker/nginx.conf or the authorization server allowlist.

Tests

tests/mcp-search-profile.test.mjs asserts the six-tool contract, unknown-tool rejection, scrapeOptions rejection, the clean outbound body, authenticated tools/list, the path-scoped metadata document, audience acceptance/rejection, and that the full surface is unaffected. It runs in CI via pnpm test.