FactReason documentation

Give your agent facts it can check.

One remote MCP server for dependency upgrade advisories, API integration facts, and component specifications. Responses are source-cited, signed, and available in compact form when context matters.

Connect an agent See an advisory

Quickstart

Discovery works without a key. Successful data lookups use a Bearer key with 50 free queries per UTC day, then prepaid credit or x402 where offered.

1Connect the remote MCP server

MCP configuration

{
  "mcpServers": {
    "factreason": {
      "type": "http",
      "url": "https://factreason.com/mcp"
    }
  }
}

2Create a free key

Shell

curl -X POST https://factreason.com/api/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

The key is the credential. Store it as a secret and send it as Authorization: Bearer <key>. Do not commit it.

3Check before upgrading

Agent tool call

{
  "name": "factreason_package_upgrade_advisory",
  "arguments": {
    "registry": "npm",
    "name": "chalk",
    "from": "4.1.2",
    "to": "5.0.0",
    "responseFormat": "compact"
  }
}

Repeatable workflows

FactReason is designed for checks an agent can run at the same decision point every time.

Before the agent...	Call	Use the result to
changes a dependency pin	`factreason_package_upgrade_advisory`	identify declared breakage and migration evidence
writes an external API call	`factreason_integration_brief`	assemble URL, auth, parameters, body, and responses
chooses a service	`factreason_discover_api`	rank indexed APIs by the required capability
uses a component	`factreason_component_spec`	verify package, pins, ratings, and source provenance
depends on a changing spec	`factreason_subscribe_spec_changes`	register a polling or webhook watch

Recommended agent rule: Before editing an npm or PyPI dependency version, call the advisory tool with the exact current and target versions. Treat missing publisher metadata as unknown, not as proof of compatibility.

Tool reference

Tool	Answer	Price after free allowance
`factreason_package_upgrade_advisory`	Declared npm/PyPI changes between exact versions	$0.020
`factreason_api_schema`	Versioned request and response schema	$0.002
`factreason_api_breaking_changes`	Computed API migration analysis; currently offline pending revalidation	Not billed while offline
`factreason_integration_brief`	Callable facts for one API integration	$0.010
`factreason_discover_api`	Capability search across indexed services	$0.005
`factreason_deprecation_scan`	Declared deprecations, sunsets, and replacements	$0.005
`factreason_auth_playbook`	Auth schemes, scopes, rate limits, and errors	$0.005
`factreason_component_spec`	Exact electronic component facts	$0.001
`factreason_subscribe_spec_changes`	Register a specification watch	Uses metered access
`factreason_create_topup_link`	Create a human checkout handoff	Free

The live machine-readable definitions remain authoritative: initialize https://factreason.com/mcp, then call tools/list. The public contract is also published in the registry repository.

Compact responses

Set responseFormat: "compact" on supported high-detail MCP tools. Compact output removes repeated prose and fields while retaining evidence and provenance. Full output remains the compatibility default.

Supported: package advisory, exact component lookup, integration brief.
Metrics use o200k_base and count the complete structured JSON payload.
Compact and full modes use the same authorization, free allowance, and price.
An unpaid 402 challenge never contains the requested record.

Token savings vary with the result. Use the returned tokenMetrics instead of assuming a fixed percentage.

Access and payment

Bearer key

Every key receives 50 successful queries per UTC day at no charge. Misses, rate-limited requests, and cached HTTP 304 revalidations are not billed. After the allowance, successful queries debit prepaid credit.

x402

Wallet-capable agents can answer an HTTP 402 challenge with USDC on Base for supported price tiers. The challenge describes payment requirements, not the protected result.

Card top-up

An agent can call factreason_create_topup_link and hand the checkout URL to a human. Optional automatic top-up is off by default and requires explicit customer consent and a monthly cap.

Never place a FactReason key or payment proof in prompts, source control, logs, or correction reports.

Errors and retries

Status	Meaning	Agent action
400	Invalid or incomplete input	Correct the named field; do not retry unchanged
401	Invalid Bearer credential	Check the key and Authorization header
402	Free allowance or credit unavailable	Pay x402 where offered or create a top-up link
404 / found false	No verified matching record	Use returned alternatives; misses are not billed
429	Rate limit reached	Wait for `Retry-After`, then retry with backoff
503	Capability deliberately unavailable or service unhealthy	Do not treat it as an empty result; retry later

Trust and evidence

Successful data responses are Ed25519-signed. Fetch the current public key from /.well-known/jwks.json and verify the response signature before relying on cached or relayed data.

X-Warehouse-Proof-Signature: response signature
X-Fact-Public-Key-Id: key identifier
X-Fact-Signature-Alg: EdDSA

Evidence fields identify the publisher-declared field and its before/after values. A signature proves the response came from FactReason; it does not turn best-effort source data into a guarantee.

Scope and limitations

Package advisories currently use publisher-declared npm and PyPI registry metadata. They can identify yanks, runtime floors, module format, exports, peers, licences, and other declared metadata changes. They do not execute packages or infer undocumented behavioral changes.

Use Context7 or publisher documentation for current usage examples, Socket/Snyk for deeper supply-chain and vulnerability analysis, and repository automation such as Dependabot or Renovate to open update pull requests. FactReason supplies the evidence check at the upgrade decision point.

Corrections

Reports are free and never consume query credit. They enter a private operator queue, are checked against a primary source, and remain separate from paid catalogue responses.

Report incorrect data Contact support