Fetchmux

FetchMux

[npm] [License] [Node] [MCP]

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/fetchmuxcd fetchmuxnpm installnpm run build
export FETCHMUX_API_KEY="a-long-random-key"export CROSSREF_ENABLED=trueexport CROSSREF_CONTACT_EMAIL="[email protected]"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 plannpm 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.

Run in Docker

cp .env.example .env    # add your keys, never commit itdocker compose up --build -dcurl 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 testsnpm run typechecknpm run lintnpm run buildnpm run dev:gatewaynpm run dev:site

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

Security issues: [email protected].

License

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