research-mcp

Paid cited research remote MCP for coding / research agents (API key auth, not OAuth).

Why pay: query-tied excerpt packs from allowlisted primaries; refuse uncited — that call is $0. Prepaid packs; meters only on billable successes.

Repo may be private; treat this README as the agent-facing contract. Live Fly host is unchanged.

Marketing site (Cloudflare Pages)

Source of truth: research-mcp-hq/www (public/). Live site: https://researchmcp.dev.

The www/ tree in this repo is a stub / mirror note only — do not point Cloudflare Pages here. MCP API origin remains on Fly; branded install URL is https://mcp.researchmcp.dev/mcp.

MCP URL (production)

https://mcp.researchmcp.dev/mcp

Health: https://mcp.researchmcp.dev/health
Server card: https://mcp.researchmcp.dev/.well-known/mcp/server-card.json
Credits meter: GET https://mcp.researchmcp.dev/billing/credits (auth’d)

{
  "mcpServers": {
    "research-mcp": {
      "url": "https://mcp.researchmcp.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Auth

Every /mcp and /billing/credits request:

• Authorization: Bearer <key> or
• X-API-Key: <key>

Keys: prepaid customer key (from Checkout success page) or break-glass API_KEYS (ops; no ledger debit).

Privacy (demand signals)

We log category mix (tool, topic bucket, host, billable vs fail=$0) — not your questions. Opt-in via DEMAND_LOG=1 on the server; default off.

Pricing (locked)

fail = $0: sample/demo, quote-gate fail, density fail, COGS abort, cancel, depth-mismatched golden, preview/parked paths (meta.billable=false, charge_usd=0).

Inspect balance + tables: GET /billing/credits → balance_cents, packs, meters_usd, fail_usd: 0. Break-glass returns { break_glass: true, balance_cents: null } (no fake balance).

When to call each tool

Live (default paid surface)

Both return the shared envelope: tldr, body, confidence, sources, gaps, as_of, plus schema_version (2026-09-14). Optional fail_gate: { reason, retryable }, claims / excerpts, retrieved_at. If quotes fail verification on source_url, the run is refused and not billed.

Preview / parked (ENABLE_PREVIEW_TOOLS=1)

Without the flag: compare_options is not registered; depth=deep is rejected (preview_required). Directory card still says do-not-call for compare/deep.

No stub billing. No 25-tool kitchen sink — two live tools by default.

Published contract

• Schema: docs/contract/schema.json
• Examples: docs/contract/examples/happy-research-brief.json, fail-gate.json
• HTTP header on responses: X-Research-MCP-Schema-Version: 2026-09-14
• Tool notes: docs/TOOLS.md

Quickstart (local)

cd /workspace/research-mcp
npm install && npm run build
API_KEYS=dev-key-1 npm start
# optional live brief path:
LIVE_RESEARCH=1 API_KEYS=dev-key-1 npm start

curl -s http://127.0.0.1:3000/health
curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer dev-key-1' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Env (high-signal)

Tests

npm run eval:all      # goldens + off-golden + pipeline
npm run test:billing  # ledger / webhook / credits meter

Layout

• src/server.ts — tool registration (finish-or-hide)
• src/billing/credits.ts — GET /billing/credits (T10 visible meter)
• src/contract.ts — schema_version + fail_gate
• docs/contract/ — published JSON Schema + examples
• ARCHITECTURE.md — transport / auth / metering

Discovery

Homepage for listings: https://researchmcp.dev, not Smithery.

Ops

See RUNBOOK.md. License: MIT.