carrierscore

FMCSA motor-carrier risk scores, monitoring, and carrier-selection evidence reports for AI agents.

CommunityOnlineNo sign-inGlobalFreeRead-only

What it can do

    What data it sees

    Do you need an account

    No: the server works without sign-in

    FMCSA motor-carrier risk scores, monitoring, and carrier-selection evidence reports for AI agents.

    How to connect

    How to connect carrierscore to Claude

    The server address to paste into Claude settings:

    https://mcp.carrierscore.io/mcp

    1. Open Claude (claude.ai or the desktop app).
    2. Go to Settings → Connectors.
    3. Click Add custom connector.
    4. Paste the server address copied below into Remote MCP server URL and click Add.
    5. In a chat, click + → Connectors and switch the new connector on.

    Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

    Authorization

    After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

    How to connect carrierscore to ChatGPT

    The server address to paste into ChatGPT settings:

    https://mcp.carrierscore.io/mcp

    1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
    2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
    3. Open Settings → Connectors and click Create.
    4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
    5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
    6. In a new chat open + → Apps/Connectors and enable the connector.

    OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

    Authorization

    On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

    How to connect carrierscore to Cursor

    The server address to paste into Cursor settings:

    https://mcp.carrierscore.io/mcp

    Fastest: click Open in Cursor below and confirm the prompt.

    Manually:

    1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
    2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
    3. Save the file. The server appears in the MCP list; authorize it there if asked.

    Authorization

    If the service needs sign-in, an authorize button appears next to the server in the MCP list.

    Server tool list (8)

    Raw names from tools/list. Only developers need these.

    carrier_lookupLook up an FMCSA-registered motor carrier's identity by US DOT number: legal name, DBA, operating status, FMCSA safety rating, fleet size (power units, drivers), physical address, and registration dates. Use this first when a booking/dispatch agent needs to confirm WHO a carrier is — that a DOT number is real, active, and matches the company name on a rate confirmation. It does not return risk indices (use carrier_score for those). Returns JSON: { dot_number, legal_name, dba_name, status_code, safety_rating, power_units, total_drivers, phy_street, phy_city, phy_state, phy_zip, add_date, mcs150_date }. Errors: 404 if the DOT is not in the FMCSA census (likely a typo or a fraudulent/never-registered carrier — treat as a red flag for booking).
    carrier_scoreGet the CarrierScore risk indices for a carrier by US DOT number: two first-class, separately validated indices (0-100, HIGHER = RISKIER), each with a full component breakdown. This is the core "is this carrier safe to book?" signal for AI booking agents. Served methodology v0.5 returns TWO indices, both population-relative and built from point-in-time public FMCSA data: - inspection_risk — inspection / compliance risk: violations and out-of-service rates per roadside inspection (24-month chronic, 6-month acute). Historically validated against the carrier's future out-of-service rate (validation block on the index). - crash_risk — crash risk: reportable crashes, fatal/injury crashes and tow-away crashes per roadside inspection (24 months). Historically validated against future reportable crashes (validation block on the index). Present BOTH indices; do not collapse them into one number. Hard flags (active out-of-service order, no active insurance filing, high-confidence reincarnated-carrier link) add explicit surcharges — a carrier with any flag deserves extra scrutiny regardless of index values. Returns JSON: { dot_number, legal_name, inspection_risk: { label, description, score, base, surcharge, percentile_basis, band, band_note, data_sufficiency, components: { <name>: { label, value, percentile, weight } }, validation: { auc_holdout, label, holdout_origins, post_selection_origin, source, text } }, crash_risk: { ...same shape... }, legacy_composite: { score, base_score, surcharge, rule, rule_text, validated: false, note }, carrier_score (backward-compatible: == legacy_composite.score under v0.5), base_score, surcharge, score_version ("0.5"), methodology_note, components (flat, backward-compatible), flags: string[], data_sufficiency (0-1, share of the components resting on observed vs neutral-imputed data), scored_as_of, disclaimer }. Older opt-in methodologies keep their shapes: v0 (six components), v0.3 (sub_indices), v0.4 (indices + composite). Interpreti
    montgomery_fileGenerate a timestamped Montgomery file — a carrier-selection evidence report — for a carrier by US DOT number. Since Montgomery v. Caribe Transport II (SCOTUS, May 2026), freight brokers are exposed to state-law negligent-selection claims and need documented, timestamped, safety-data-based carrier selection. This report is that artifact: the two risk indices (inspection / compliance risk and crash risk, each with its components, percentiles, activity-band context and its own historical-validation line), the legacy composite (labelled backward-compatibility only), hard flags, FMCSA safety rating, and the methodology disclaimer, dated as of the scoring run. A booking agent should generate and retain this file at the moment a carrier is selected for a load. Args: - dot_number: US DOT number, digits only - format: "text" (default; the filing-ready plain-text report, available on the free tier) or "json" (structured fields; requires an API key on the monitor or compliance tier) Returns: format="text" gives the plain-text report (structured field report_text); format="json" gives structured fields { report, generated, dot_number, legal_name, dba_name, safety_rating, status_code, power_units, inspection_risk, crash_risk, legacy_composite (v0.5), carrier_score (backward-compatible), components, flags, data_sufficiency, score_version, scored_as_of, disclaimer } (v0.4 parquets return indices + composite instead). Every report embeds the disclaimer verbatim — keep it when storing or quoting the report. Audit archive (paid tiers): every report generated with an API key is stored immutably server-side and the result carries audit_entry_id + sha256 (SHA-256 of the plain-text report). Quote both when citing the report; later, verify_evidence(entry_id) proves the archived copy is unchanged and audit_entries lists what was generated. Monitor keys can retrieve the last 90 days (2,000 reports/month); Compliance keys have unlimited retention and reports. Errors: 403 if format=
    monitor_carriersBatch risk check for a list of carriers by US DOT number (max 100 per call): score summary and hard flags for each. Use when an agent is screening multiple candidate carriers for a load, or re-checking a broker's active carrier roster ("did any of my carriers pick up an out-of-service order or drop insurance?"). For a full breakdown of any single carrier that looks risky here, follow up with carrier_score or montgomery_file. Args: - dot_numbers: array of DOT number strings, 1-100 entries Returns JSON: { scored_as_of, requested, found, carriers: [{ dot_number, legal_name, inspection_risk (0-100 inspection / compliance risk index, higher = riskier), crash_risk (0-100 crash risk index), carrier_score (legacy composite under v0.5 — backward compatibility only; use the two indices), data_sufficiency, flags: string[] }], not_found: string[], disclaimer }. DOTs in not_found are absent from the scored population — verify them with carrier_lookup; an unknown DOT on your roster is itself a red flag. Errors: 400 if the list is empty or exceeds 100 (split into batches); 503 if scores are not computed yet.
    save_carrier_listSave a named list of carriers (by US DOT number) for continuous monitoring. Requires a paid CarrierScore API key (Monitor or Compliance tier) — connect with your key via OAuth (or set CARRIERSCORE_API_KEY on a self-hosted server); the free tier gets a 403 with an upgrade link. Once saved, CarrierScore diffs every carrier on the list against the previous day's scoring run after each daily run and records alerts: new out-of-service order (critical), operating authority lost (critical), insurance filing lapsed (high), operating status leaving Active (high), risk score up 10+ points (medium), high-confidence reincarnated-carrier link appearing (medium). Alerts are always retrievable with list_alerts; optionally they are also pushed to a webhook (JSON POST, HMAC-signed via the X-CarrierScore-Signature header with the per-key secret from GET /v1/lists) and/or summarized in one daily digest email. Use this when a broker asks to "watch" or "keep an eye on" their carrier roster. Caps: 500 DOTs total across all lists on the Monitor tier, 5000 on Compliance; up to 50 lists per key. Saving the same DOT twice in one list is deduped. Args: - name: short label for the list (1-100 chars) - dot_numbers: array of DOT number strings (1-8 digits each) - webhook_url (optional): https URL to POST new alerts to - email (optional): address for the daily digest Returns JSON: { list_id, name, dots, created, updated, webhook_url?, email? }. Keep list_id — list_alerts needs it. Errors: 403 without a paid key; 400 on invalid DOTs, empty list, or exceeding the tier cap (message says which); 401 bad key.
    list_alertsRetrieve the alert history for a saved carrier list (see save_carrier_list), newest first. Requires the same paid API key that saved the list. Each alert records one change detected between consecutive daily scoring runs for one carrier: type (oos_order_activated, authority_lost, insurance_lapsed, status_changed, inspection_risk_jump, crash_risk_jump, score_jump, reincarnation_link), severity (critical / high / medium / low), the field that changed with its before/after values, the DOT and legal name, and the scoring dates compared. inspection_risk_jump / crash_risk_jump (index base up >= 10 points, medium) are the primary deterioration signals; score_jump on the legacy composite is emitted at low severity for backward compatibility. Use it to answer "did anything change on my carrier list?" — critical alerts (new OOS order, authority lost) mean the carrier should not be dispatched until verified; follow up with carrier_score or montgomery_file for the full picture. Args: - list_id: the lst_... id returned by save_carrier_list - since (optional): YYYY-MM-DD; only alerts from scoring runs on/after this date Returns JSON: { list_id, since, count, alerts: [{ ts, as_of, prev_as_of, list_id, list_name, dot, legal_name, type, severity, field, before, after }] }. An empty alerts array means no monitored change since the given date (alerts only exist once two daily scoring runs have happened). Errors: 403 without a paid key; 404 if the list id is unknown for this key; 400 if since is not YYYY-MM-DD.
    audit_entriesList the immutable audit-archive entries for the caller's API key: every Montgomery evidence report the key generated (text or json), newest first, each with its entry id, generation timestamp, DOT number, scoring date, methodology version and the SHA-256 of the archived report text. Requires a paid CarrierScore API key. Use it to answer "which carriers did we generate evidence for, and when?" and to find the entry id to cite or verify for a given carrier and date. Monitor keys see the last 90 days; Compliance keys see everything ever archived. Args: - dot_number (optional): only entries for this US DOT number - since (optional): YYYY-MM-DD; only entries generated on/after this date (UTC) - limit (optional): 1-500, default 50 Returns JSON: { tier, retention_days, total_entries, matched, count, entries: [{ entry_id, generated_at, dot_number, sha256, format_requested, scored_as_of, score_version }] }. Errors: 403 without a paid key; 400 if since is malformed.
    verify_evidenceVerify an archived Montgomery evidence report by its audit entry id: CarrierScore re-reads the immutable stored copy, recomputes its SHA-256 and reports whether it matches the hash recorded at generation time (and, optionally, a hash the caller supplies — e.g. the sha256 printed on a broker's filed copy). Requires the same paid API key that generated the report. Use it when a broker or auditor needs to prove that a filed evidence report is exactly what CarrierScore produced on the stated date. match=true means the archived report is byte-identical to what was served; match_supplied compares against the caller's own hash. Follow up with the audit_entries list to find ids, or with montgomery_file to generate a fresh report. Args: - entry_id: the audit_entry_id returned by montgomery_file (also listed by audit_entries) - sha256 (optional): a 64-hex SHA-256 to compare against the archived report (text or canonical json) Returns JSON: { entry_id, dot_number, generated_at, scored_as_of, score_version, format_requested, sha256_stored, sha256_computed, match, sha256_json_stored, sha256_json_computed, match_json, sha256_supplied?, match_supplied? }. Errors: 403 without a paid key, or (Monitor tier) if the entry is older than the 90-day retrieval window; 404 if the entry id is unknown for this key.