Fetchmux MCP Server

FetchMux

FetchMux is a provider-neutral retrieval router for AI agents. A client sends one stable search request; FetchMux selects an eligible customer-configured provider, enforces cost and deadline limits, normalizes the evidence, and returns an auditable route receipt.

One retrieval API. The right provider for every request.

The founding product is deliberately narrow: public-web search and page retrieval through customer-owned provider accounts, plus an opt-in public scholarly-metadata route. It is not a generic API proxy, pooled-credit reseller, or claim that upstream APIs are interchangeable.

Status

Founding-pilot build. The machine-readable discovery site is live at fetchmux.com, while the gateway remains private and single-tenant. FetchMux is a provisional working name pending formal trademark and company-name clearance. No provider partnership, endorsement, or resale right is implied.

What exists today:

• deterministic policy ranking with task, cost, quality, latency, and reliability inputs;
• hard pre-request budgets and absolute deadlines;
• retryable-failure-only fallback and an in-memory circuit breaker;
• BYOK adapters for Brave, Tavily, Exa, and Firecrawl, plus an explicit-opt-in Crossref scholarly metadata adapter that needs no provider credential;
• protected REST, typed TypeScript SDK, and read-only MCP interfaces;
• a 24-case reproducible benchmark workload with a zero-network dry run;
• a browser-tested founding site and local container packaging;
• verified hello@fetchmux.com pilot intake and security@fetchmux.com vulnerability routing;
• a live, operator-IP-restricted Azure staging gateway deployed by reproducible templates and secret-safe scripts, with zero provider keys enabled;
• a protected, real-upstream proof through the hardened local production image using Crossref scholarly metadata.

What does not exist yet:

• hosted multi-tenant credential storage;
• provider credit resale or autonomous provider signup;
• learned routing backed by customer outcomes;
• a production or public hosted gateway, public package, completed live provider benchmark, or self-serve signup and billing.

Prerequisites

• Node.js 24 and npm 11;
• Git;
• Docker Desktop only if using the container path;
• at least one supported provider key, or an explicitly enabled Crossref configuration, for a ready gateway.

Quick start

Install, build, and test from the repository root:

npm clean-install
npm run build
npm test

Set a gateway key and one provider key in the current PowerShell session. Cost values must come from the operator's actual provider plan; the number below is only a shape placeholder and must be replaced before using dollar budgets.

$env:FETCHMUX_API_KEY = "replace-with-a-long-random-gateway-key"
$env:BRAVE_API_KEY = "replace-with-your-provider-key"
$env:BRAVE_COST_PER_REQUEST_USD = "replace-with-your-real-cost"
npm run dev:gateway

For a no-provider-account technical proof, Crossref's public REST API can be enabled explicitly. Use a real monitored contact address as required by Crossref's polite-pool guidance:

$env:FETCHMUX_API_KEY = "replace-with-a-long-random-gateway-key"
$env:CROSSREF_ENABLED = "true"
$env:CROSSREF_CONTACT_EMAIL = "replace-with-your-contact@example.com"
npm run dev:gateway

Send the same request shape with task = "scholarly". This route returns bibliographic metadata and DOI links only; it does not copy abstracts or provide page-content extraction.

In another terminal:

$headers = @{
  Authorization = "Bearer replace-with-a-long-random-gateway-key"
  "Content-Type" = "application/json"
}
$body = @{
  query = "latest stable Node.js release"
  task = "fresh_facts"
  priority = "balanced"
  maxCostUsd = 0.02
  maxLatencyMs = 8000
  limit = 8
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8787/v1/search" -Headers $headers -Body $body

/health reports process health. /ready returns 503 until at least one credentialed provider or the valid opt-in Crossref route is configured. Protected /v1/* routes return 503 if FetchMux authentication itself has no key.

Configuration

The process does not automatically load .env during local Node development. Set variables in the shell or use an operator-controlled process manager. Docker Compose reads the ignored .env file.

See provider configuration before enabling maxCostUsd.

Interfaces

REST

The complete FetchMux contract is docs/openapi.yaml. It is not an upstream provider contract.

TypeScript SDK

The SDK is a workspace package in the founding build; it has not been published to a registry.

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 response = await client.search({
  query: "latest stable Node.js release",
  task: "fresh_facts",
  maxCostUsd: 0.02,
});

MCP

Build the workspace, start the gateway, and add the compiled stdio server to an MCP client:

{
  "mcpServers": {
    "fetchmux": {
      "command": "node",
      "args": ["C:/absolute/path/to/fetchmux/apps/mcp/dist/main.js"],
      "env": {
        "FETCHMUX_BASE_URL": "http://127.0.0.1:8787/",
        "FETCHMUX_API_KEY": "replace-with-the-gateway-key"
      }
    }
  }
}

The tools are search_web and preview_search_route; both are annotated read-only.

Benchmark

Validate all 96 founding case-provider pairs without network calls or credits:

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

Live mode is deliberately harder to trigger. It requires provider credentials, explicit --confirm-live, and an ignored output file:

$env:FETCHMUX_CODE_VERSION = git rev-parse HEAD
npm run benchmark -- --workload benchmarks/workloads/founding-v1.json --mode live --confirm-live --output benchmarks/results/founding-v1-live.json

Live reports are private by default. Provider terms can restrict benchmarking, storage, or performance disclosure; review the account's accepted terms before running live and obtain counsel and any required written permission before sharing results. Read the benchmark methodology before interpreting a run.

Docker

Copy the environment template, enter real secrets locally, and start the loopback-only container:

Copy-Item .env.example .env
# Edit .env locally. Never commit it.
docker compose up --build -d
Invoke-RestMethod http://127.0.0.1:8787/health
docker compose logs --follow gateway

The build and runtime image digests pin the official Node 24 build image and supported Distroless Node 24 Debian 13 nonroot runtime. The image includes production dependencies only for the gateway and its two internal packages, drops Linux capabilities in Compose, supports a read-only root filesystem, and receives provider credentials only at container start.

Development commands

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

Operating documentation

• Local development
• Public release
• Launch kit
• Deployment
• Azure staging
• Provider configuration
• Incident response
• Data handling
• Product decision
• Operating plan
• Validation scorecard
• Risk register
• Founding pilot
• Discovery script
• Outreach sequences
• Pilot scorecard
• Weekly operating review
• Partnership brief
• Legal readiness checklist
• Market evidence
• Source register
• Real-provider proof, 2026-07-18
• Site deployment evidence, 2026-07-18

Logging and persistence

Gateway route events go to stdout as structured JSON and exclude query text, provider keys, raw provider bodies, and result content. The founding gateway has no database and no built-in metrics retention. Configure process-log retention deliberately and treat normalized URLs and provider metadata returned to callers as customer data.

License

Apache-2.0. The license grant takes practical effect when the repository is made public; swap the LICENSE file first if a different license is preferred. See the public release runbook for the full release sequence.