Fetchmux

FetchMux

One search endpoint for AI agents. Put a router in front of Brave, Tavily, Exa, Firecrawl, and Crossref. Every request carries a hard cost ceiling and deadline; every response comes back with a receipt that says which provider ran, why, and what it cost.

Your agents stop hard-coding a provider into prompts and app code. They send one request shape; the gateway picks an eligible provider under a policy you control, enforces the budget and deadline before the call, retries safely on failure, and returns normalized results plus a full trace. You keep your provider keys — they never leave your gateway.

The receipt

Nothing is a black box. Every /v1/search response carries the routing decision:

"route": {

"selectedProvider": "brave", "attemptedProviders": ["brave"], "reasonCodes": ["TASK_MATCH", "WITHIN_BUDGET", "RELIABILITY_WEIGHT"], "attempts": [ { "provider": "brave", "outcome": "success", "latencyMs": 640, "estimatedCostUsd": 0.005 } ], "estimatedCostUsd": 0.005, "latencyMs": 640, "fallbackUsed": false, "traceId": "rt_b400e7c8" }

How it routes

  agent  ──▶  { query · task · maxCostUsd · maxLatencyMs }

│ ▼ ┌──────────────┐ your keys │ FetchMux │ ─────▶ Brave · Tavily · Exa │ policy │ Firecrawl · Crossref └──────────────┘ ◀───── (bring your own) │ ▼ agent ◀── evidence[] + route receipt

A provider is eligible only when its credentials, task fit, circuit state, spend, and deadline all pass. Budgets and deadlines are eligibility rules, not best-effort hints. Fallback happens only on retryable failures.

Quick start

No provider account needed — the public Crossref route runs out of the box:

git clone https://github.com/krutftw/fetchmux

cd fetchmux npm install npm run build

export FETCHMUX_API_KEY="a-long-random-key" export CROSSREF_ENABLED=true export CROSSREF_CONTACT_EMAIL="you@example.com" npm run dev:gateway

From another shell:

curl http://127.0.0.1:8787/v1/search \

-H "Authorization: Bearer a-long-random-key" \ -H "Content-Type: application/json" \ -d '{ "query": "retrieval augmented generation", "task": "scholarly", "maxLatencyMs": 8000 }'

To route real web search, set a provider key and use a web task instead:

export FETCHMUX_API_KEY="a-long-random-key"

export BRAVE_API_KEY="your-brave-key" export BRAVE_COST_PER_REQUEST_USD="0.005" # from your provider plan npm run dev:gateway

New to Firecrawl? New accounts get 10% off the first month through this link (referral — FetchMux earns a small commission, no extra cost to you).

Use it from an agent

Point any MCP client (Claude, Cursor, and friends) at the published server:

{

"mcpServers": { "fetchmux": { "command": "npx", "args": ["-y", "@fetchmux/mcp"], "env": { "FETCHMUX_BASE_URL": "http://127.0.0.1:8787/", "FETCHMUX_API_KEY": "your-gateway-key" } } } }

Two read-only tools: search_web and preview_search_route.

Or use the typed SDK, @fetchmux/sdk:

import { FetchMux } from "@fetchmux/sdk";

const client = new FetchMux({ baseUrl: "http://127.0.0.1:8787/", apiKey: process.env.FETCHMUX_API_KEY, fetch: globalThis.fetch.bind(globalThis), });

const res = await client.search({ query: "latest stable Node.js release", task: "fresh_facts", maxCostUsd: 0.02, });

Providers

Bring your own key for each. Set the matching *_API_KEY, plus an optional *_COST_PER_REQUEST_USD if you want dollar budgets enforced.

REST endpoints

Full contract: docs/openapi.yaml.

All configuration variables

The process does not auto-load .env in local Node development; set variables in the shell or a process manager. Docker Compose reads the ignored .env file.

See provider configuration before enabling maxCostUsd.

Run in Docker

cp .env.example .env    # add your keys, never commit it

docker compose up --build -d curl http://127.0.0.1:8787/health

Non-root Distroless image: Linux capabilities dropped, read-only root filesystem, provider credentials passed only at container start.

Benchmark

Validate every case and provider pairing with no network calls or credits:

npm run benchmark -- --workload benchmarks/workloads/founding-v1.json --mode dry-run

Live mode needs provider keys and an explicit --confirm-live. Check each provider's terms before publishing results — see the benchmark methodology.

What it is (and isn't)

Open source, self-hosted, single-tenant, BYOK. Route events go to stdout as JSON and exclude your query text, keys, and result content by default. No database, no telemetry.

It is not a hosted service, a pooled-credit reseller, or a claim that these providers are interchangeable. Provider names are the adapters it ships with, not partnerships. A hosted version is on the roadmap — star the repo to follow.

Development

npm test          # 232 tests

npm run typecheck npm run lint npm run build npm run dev:gateway npm run dev:site

More docs: product design · local development · deployment · provider configuration · data handling · incident response

Security issues: security@fetchmux.com.

License

Apache-2.0. Free to self-host, modify, and redistribute.