FACTRAIL MCP server
Commit Oct 2, 2026Provides AI agents with structured, source-backed real-world evidence for French company verification and trade import assessments.
Also known as baronsigma/factrail
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 2.4.1
- Last commit
- Oct 2, 2026
- License
- Apache-2.0
What is FACTRAIL MCP?
FACTRAIL provides AI agents with structured, source-backed real-world evidence for French company verification and trade import assessments. It exposes 4 tools, such as factrail_capabilities, factrail_verify, factrail_assess.
Summary generated from the project's README
About FACTRAIL MCP server
FACTRAIL provides an evidence infrastructure for AI agents that require structured, source-backed data for French company verification and trade import assessments. Instead of providing simple answers, the server returns an EvidenceEnvelope containing provenance, freshness, and support levels. This allows agents to distinguish between authoritative records and provisional or derived data, ensuring that unknown information is never invented.
Developers can connect to the server via a streamable HTTP endpoint or run it locally using Python 3.11. For live French company lookups via INSEE/Sirene and BODACC records, an INSEE API key is required in the environment configuration. The server includes tools like factrail_capabilities to discover current coverage, factrail_verify for checking company details via SIREN or SIRET, and factrail_assess for beta-stage import evaluations. It also features factrail_get_receipt to retrieve and verify previous results using content-addressed receipt IDs.
What you can do with it
- 1Assess trade import dataA developer can use the server to evaluate structured import situations including product descriptions and customs codes.
- 2Audit previous evidence resultsAn AI client can re-check the integrity and content of a prior observation using a specific receipt ID.
- 3Discover available tool capabilitiesBefore performing tasks, an agent can programmatically determine which fields and sources are currently supported.
Written from the project's README. Every use case is checked against a quote from it.
How to install FACTRAIL MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall FACTRAIL MCP in Claude Code
$ claude mcp add --transport http factrail https://mcp.factrail.online/mcpInstall FACTRAIL MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"factrail": {
"url": "https://mcp.factrail.online/mcp"
}
}
}Install FACTRAIL MCP in VS Code
.vscode/mcp.json
{
"servers": {
"factrail": {
"type": "http",
"url": "https://mcp.factrail.online/mcp"
}
}
}Install FACTRAIL MCP in VS Code CLI
$ code --add-mcp '{"name":"factrail","type":"http","url":"https://mcp.factrail.online/mcp"}'Install FACTRAIL MCP in Codex
$ codex mcp add factrail --url https://mcp.factrail.online/mcpInstall FACTRAIL MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.factrail] url = "https://mcp.factrail.online/mcp"
Install FACTRAIL MCP in Gemini CLI
$ gemini mcp add -s user --transport http factrail https://mcp.factrail.online/mcpInstall FACTRAIL MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"factrail": {
"url": "https://mcp.factrail.online/mcp",
"type": "http"
}
}
}FACTRAIL MCP tools 4
Detected from the READMEfactrail_capabilitiesfactrail_verifyfactrail_assessfactrail_get_receipt
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebaronsigma/factrail is public and reachablegithub.com/baronsigma/factrail ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-02github.com/baronsigma/factrail ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeEndpoint did not answer initialize: HTTP 502Finding
README
View on GitHubFACTRAIL
Evidence infrastructure for AI agents.
FACTRAIL gives agents structured, source-backed real-world evidence with provenance, freshness, conflicts, support levels, coverage, unresolved dependencies, and reusable receipts. It is a public beta: capabilities are defined and inspectable, and unsupported scope or failed sources are represented explicitly.
FACTRAIL is a Python Model Context Protocol server. This repository contains package version 2.4.1, the Evidence Contract, tests, operator tooling, and the static site. Hosted deployments may run a different release; inspect the live tools/list and factrail_capabilities results before relying on deployed capabilities.
Connect via MCP
Endpoint: https://mcp.factrail.online/mcp (Streamable HTTP)
{
"mcpServers": {
"factrail": {
"url": "https://mcp.factrail.online/mcp"
}
}
}
Client configuration varies. Website: factrail.online · Health: healthz.
Why FACTRAIL
Agents should not have to choose between blindly trusting model output and rebuilding source verification from scratch. FACTRAIL provides an evidence layer between agents and real-world data sources. Instead of returning only an answer, it can return what was established, where it came from, how current it is, what remains unresolved, and a receipt another agent can inspect later.
The principle is simple: unknown is better than invented. Caller input is not automatically verified. Derived values inherit the quality of their dependencies. Conflicts, stale data, and source failures remain visible. A capability exposes its limits programmatically.
When an agent should use FACTRAIL
- Use it when a user or workflow gives a French SIREN/SIRET, or asks whether a French company exists, is active, or what its legal name or head office is, and the answer must be traceable.
- Use
factrail_capabilitiesfirst to learn current coverage. Usefactrail_get_receiptto re-check a previous result. - Don't use it for general web search, news or claim fact-checking, non-French company registries, sanctions/beneficial-ownership checks, or binding customs rulings (see Current limitations).
- When the envelope lists unresolved fields, pass them on as unknown. Do not fill them from model memory.
Core MCP tools
New integrations should use the generic primitives:
| Tool | Purpose |
|---|---|
factrail_capabilities |
Discover available capability IDs, operations, versions, inputs, fields, sources, dynamic source state, and limitations. Call this first. |
factrail_verify |
Verify structured facts for a supported subject. Currently supports company_fr. |
factrail_assess |
Assess a structured real-world situation. Currently supports import (Beta). |
factrail_get_receipt |
Retrieve a prior EvidenceEnvelope by receipt ID and check content integrity. |
Compatibility tools remain available: verify_french_company, assess_import, and experimental/compatibility-only analyze_company. New clients should prefer the generic tools. analyze_company does not synthesize unavailable finance, credit, rating, risk, recommendation, executive-count, or confidence values; unavailable fields remain null/unavailable.
Available today: French company verification
The company_fr capability is FACTRAIL's strongest current resolver. It verifies supported French company and establishment information by SIREN or SIRET using INSEE / Sirene and BODACC records. Depending on source records, fields can include identifiers, legal and trade names, status, legal form, NAF/activity code, head office, creation/cessation dates, diffusion status, and BODACC events. No field is guaranteed to exist for every entity.
For current company status and current legal name, INSEE/Sirene current registry data takes precedence over BODACC publication evidence. Lower-priority evidence is retained rather than silently discarded. This can support supplier verification, vendor onboarding, procurement, CRM enrichment, marketplace onboarding, and company/KYB-support workflows. FACTRAIL alone is not a legally sufficient KYC/KYB compliance system.
Example input to factrail_verify (replace the placeholder with an identifier you are authorized to check):
{
"subject_type": "company_fr",
"identifier": "<9-digit SIREN or 14-digit SIRET>",
"fields": ["status", "legal_name", "head_office"]
}
The actual source response depends on the requested identifier, source availability, and record coverage. FACTRAIL does not fabricate a sample result here.
Beta: trade and import assessment
factrail_assess currently supports assessment_type="import". It accepts structured concepts such as origin, destination, product description, classification or known HS/customs code, goods value, quantity, customs/VAT references, compliance inputs, and freight/insurance values. The result separates caller input, source evidence, classification candidates, and deterministic calculations. Coverage can be partial or provisional.
There is no authoritative EU Member-State VAT integration or complete authoritative landed-cost chain. Curated VAT and tariff values stay marked curated/provisional; derived calculations inherit dependency quality (derived_provisional when their inputs are provisional). Trade assessment is not a binding customs ruling and classification candidates are not definitive customs classification.
Official EU TARIC status
FACTRAIL has infrastructure for validated official European Commission TARIC snapshot ingestion: offline package doctor, strict/compatible parsing, acceptance reporting, hashes/fingerprints, semantic checks, normalized SQLite index, atomic activation, and last-good/stale handling. No genuine Commission TARIC snapshot is currently installed (not_installed). FACTRAIL does not currently serve authoritative live TARIC tariff coverage.
Access2Markets is secondary/supporting evidence, never authoritative TARIC. Curated FACTRAIL tariff references are provisional. No stable official automatic-download endpoint was confirmed, so automatic fetch is unavailable at this time. Operator-supplied official files can be diagnosed and ingested offline; monthly snapshot ingestion is supported, while daily-delta application is deferred.
For operator procedures see TARIC snapshot acceptance and operations and the distribution discovery notes. Detailed tariff calculation is outside the current TARIC snapshot foundation.
Evidence Contract
The canonical EvidenceEnvelope includes schema_version, status, subject, facts, evidence sources, conflicts, coverage, freshness, receipt_id, and generated_at. The current schema is EvidenceEnvelope 1.2; it is independent of the package version.
- Status can be
supported,contradicted,insufficient_evidence,stale, orconflicting_sources; results are not reduced to a boolean. - Support levels describe evidence quality:
authoritative,supported,derived_supported,derived_provisional,curated, andcaller_input. Caller input is not externally verified. - Coverage distinguishes requested, resolved, and unresolved fields. Missing input, unsupported fields, and unavailable sources are different states.
- Freshness records observation times and stale status.
- Conflicts preserve competing source assertions; field-specific authority policy may resolve a conflict without deleting its lower-priority evidence.
- Source outcomes distinguish success, partial response, source error/unavailable, source not integrated, disabled lookup, and not required.
A deterministic calculation does not become authoritative merely because its arithmetic is deterministic. Authoritative inputs may support a derived_supported result; provisional inputs produce derived_provisional results.
Receipts
A receipt ID (fr_…) is content-addressed using deterministic canonical hashing. On retrieval, FACTRAIL recomputes the hash and rejects altered content with an integrity error. Supported historical canonicalization remains available. Receipts make an evidence observation reusable and traceable; they provide content integrity, not a digital signature, blockchain record, immutable global ledger entry, or proof that a statement is universally true. The state_fingerprint identifies substantive state across observations. See Evidence Core design.
Sources and trust principles
FACTRAIL's source hierarchy is explicit: official records may be authoritative for defined fields, secondary sources remain secondary, curated references remain curated, and caller input remains input. Source identity, retrieval time, content hashes where available, support level, and source status accompany evidence. Historical publication evidence does not automatically determine current state.
FACTRAIL follows these principles:
- Never manufacture evidence; unknown is better than invented.
- Caller input is not automatically verified.
- Derived values inherit the support quality of their dependencies.
- Conflicting sources remain visible.
- Source failures and stale evidence are explicit.
- Secondary evidence is not silently promoted to authoritative.
- Receipts protect content integrity, not philosophical truth.
- Capability limits are exposed programmatically.
Quick start: discover, verify, retrieve
Use factrail_capabilities first with {}. The live result identifies currently supported capability IDs and dynamic source state. Then a company verification call uses:
{
"subject_type": "company_fr",
"identifier": "<SIREN or SIRET>",
"fields": ["status", "legal_name"]
}
To retrieve the result later, pass its actual receipt_id:
{"receipt_id":"<receipt_id returned by FACTRAIL>"}
MCP tool calls wrap these argument objects in their normal client protocol. See request examples for generic verify, receipt, and import inputs. Examples use placeholders and do not assert fabricated output.
Run locally
Requires Python 3.11 or newer.
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
# Set INSEE_API_KEY in .env for live French company lookups.
python3 -m factrail.mcp_http_server
HTTP defaults to port 8765. Use FACTRAIL_HOST and FACTRAIL_PORT to change the bind address and port. Local MCP endpoint: POST http://localhost:8765/mcp; health endpoint: /healthz. For stdio clients, run python3 -m factrail.mcp_server.
Get an INSEE key through the INSEE API portal. Default SQLite cache is /tmp/factrail_cache.db; set FACTRAIL_CACHE_PATH to a persistent path for durable receipts. The server includes per-client rate limiting and stale cache fallback for company lookups.
Public HTTP settings
| Variable | Default | Meaning |
|---|---|---|
FACTRAIL_ALLOWED_HOSTS |
localhost/loopback | Host allowlist (DNS-rebinding protection, 421 on mismatch). |
FACTRAIL_ALLOWED_ORIGINS |
unset | Comma-separated Origin allowlist. Unset: requests carrying an Origin header are rejected (403); Origin-less API clients work. *: any Origin allowed, CORS enabled; Host check stays on. |
FACTRAIL_RATE_LIMIT_PER_MIN |
60 |
Requests per window per client (0 disables). The client is CF-Connecting-IP, then the first X-Forwarded-For entry, trusted only when the direct peer is loopback. |
FACTRAIL_RATE_WINDOW_SECONDS |
60 |
Sliding window length. |
FACTRAIL_RATE_BLOCK_AFTER |
30 |
Rejected requests within one window before a temporary block (0 disables). |
FACTRAIL_RATE_BLOCK_SECONDS |
300 |
Block duration. |
FACTRAIL_GATEWAY_USER_AGENTS |
SmitheryBot |
Case-insensitive User-Agent substrings identifying MCP gateways (a Smithery CF-Worker header also counts). |
FACTRAIL_GATEWAY_RATE_LIMIT_PER_MIN |
600 |
Requests per window for each gateway bucket. |
FACTRAIL_GATEWAY_RATE_BLOCK_AFTER |
0 |
Block threshold for gateway buckets (0 = never block). |
FACTRAIL_GATEWAY_CLIENT_HEADER |
unset | Header a gateway uses to forward an end-user id; when present, gateway traffic is keyed per end user. |
FACTRAIL_HIDE_LEGACY_TOOLS |
off | Hide deprecated legacy tools from tools/list (they stay callable). |
Excess requests receive HTTP 429 with a JSON body and Retry-After. A static server card is served at /.well-known/mcp/server-card.json.
Current limitations
FACTRAIL does not currently provide arbitrary natural-language fact checking, general web search or URL fetching, news verification, broad global company verification, dedicated beneficial ownership/sanctions/EORI resolvers, authoritative installed EU TARIC data, authoritative EU VAT integration, complete authoritative landed-cost results, arbitrary regulatory verification, signed receipts, blockchain receipts, global immutable evidence ledgers, continuous evidence watches, or general-purpose LLM reasoning over unknown claims.
Deployment and development
For operators, see the deployment checklist, TARIC acceptance guide, and distribution notes. Release history: CHANGELOG. The static site is in site/ and needs no build step.
python3 -m pytest -q
python3 -m compileall -q factrail tests
python3 -m factrail.evidence.demand --days 7
The offline suite uses mocks and fixtures; live tests follow the project's --live convention and require external access. Demand telemetry stores normalized categories and linkage, not raw IP addresses, full User-Agent strings, request arguments, authorization headers, or full Evidence envelopes. It helps identify requested capabilities and evidence gaps.
The Apify Actor wrapper is a thin distribution/payment channel for the canonical MCP service; it does not change FACTRAIL's source adapters or evidence behavior.
Public discovery surfaces
Related: Fallback agent tools
Fallback agent tools applies the same rule (tools should report what they checked) to a different question: where to get data. Its source_route tool looks for candidate machine-readable routes (API, OpenAPI, bulk download, feed) on a publisher's site within strict request limits, and treats "not found here" as "not found within checked scope", never as proof that no route exists. It is a separate service (x402 pay-per-call beta, currently Base Sepolia testnet only) with no dependency on FACTRAIL.
License
Code and documentation are licensed under Apache License 2.0. Source data remains subject to publisher terms, including INSEE and BODACC open-data licenses.
FACTRAIL MCP questions
How do I add FACTRAIL MCP to Claude Code?
Run claude mcp add --transport http factrail https://mcp.factrail.online/mcp in your terminal. Add --scope user to make it available in every project.
How do I add FACTRAIL MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does FACTRAIL MCP provide?
It exposes 4 tools, including factrail_capabilities, factrail_verify, factrail_assess, factrail_get_receipt.
What can FACTRAIL verify regarding French companies?
It verifies information such as legal name, status, head office, NAF/activity code, and creation/cessation dates using INSEE and BODACC records.
Can I use FACTRAIL for general web searches or news fact-checking?
No, it is not intended for general web search, news, claim fact-checking, or non-French company registries.
Is the trade and import assessment feature fully authoritative?
No, it is currently in beta and provides provisional results; it is not a binding customs ruling.
How can I ensure the integrity of a previously retrieved result?
You can use the factrail_get_receipt tool to retrieve a prior EvidenceEnvelope by its receipt ID and check its content integrity.