Connect an AI assistant to CarrierScrub

Before you start

1. Any plan works, including Pay-as-you-go at $0 a month. On Agency, checks are unlimited. On Pay-as-you-go and Small Brokerage, each lookup_carrier call uses one of your brokerage's 25 free lookups that month, then a $1.00 credit, and a carrier you already checked today is free. An owner or admin buys credits in Admin, then Billing.
2. claude.ai, Claude Desktop and the Claude mobile apps connect by signing in, with no key to copy. Skip to claude.ai.
3. Other clients use an API key. An owner or admin opens Admin, then API keys, and clicks New key. Name it after the assistant and the person using it, for example “Cursor, Dana”, so the audit log shows which one ran each check and you can revoke one without breaking the others.
4. Copy the key when it appears. It starts with cs_live_. CarrierScrub stores only a hash of it, so it can't be shown again; if you lose it, revoke it and make a new one.

In the key examples below, replace cs_live_YOUR_KEY with your key.

claude.ai, Claude Desktop and mobile

These connect by signing in to CarrierScrub, so there is nothing to copy or install.

1. In Claude, open your connector settings: Settings (or Customize), then Connectors.
2. Choose Add custom connector. Name it CarrierScrub and enter https://carrierscrub.com/mcp. Leave the advanced OAuth settings empty.
3. Click Add, then Connect. A CarrierScrub window opens; sign in if it asks.
4. Check that the page names Claude and says it sends you back to claude.ai, choose the brokerage, and click Allow.

The connector then works in Claude on the web, on the desktop and on your phone. Checks run as you, in the brokerage you chose, and show in its audit log as a connected app. An owner or admin can see and disconnect every connection in Admin, under Connected apps.

Claude Code

Run this once in a terminal:

claude mcp add --transport http carrierscrub https://carrierscrub.com/mcp \
  --header "Authorization: Bearer cs_live_YOUR_KEY"

That adds the server for the current project only. Add --scope user to make it available in every project. Run claude mcp list to confirm it connected, then ask something like “Check USDOT 8893375 with CarrierScrub.”

Claude Code can sign in instead of using a key. Leave out the --header line, then run /mcp inside Claude Code, choose carrierscrub, and approve it in the browser window that opens.

Cursor

Add this to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:

{
  "mcpServers": {
    "carrierscrub": {
      "url": "https://carrierscrub.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CARRIERSCRUB_API_KEY}"
      }
    }
  }
}

Set CARRIERSCRUB_API_KEY to your key in the environment Cursor starts from. That keeps the key out of the file, which matters most for a project file that could be committed to a repository.

VS Code

Add this to .vscode/mcp.json in your workspace. VS Code asks for the key the first time the server starts and masks it as you type, so it is never written into the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "carrierscrub-key",
      "description": "CarrierScrub API key (cs_live_...)",
      "password": true
    }
  ],
  "servers": {
    "carrierscrub": {
      "type": "http",
      "url": "https://carrierscrub.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:carrierscrub-key}"
      }
    }
  }
}

Claude Desktop with an API key

1. Install Node.js version 18 or later.
2. In Claude Desktop, open Settings, then Developer, then Edit Config. That opens claude_desktop_config.json.
3. Add the server below, save, and restart Claude Desktop.

{
  "mcpServers": {
    "carrierscrub": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://carrierscrub.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${CARRIERSCRUB_AUTH}"
      ],
      "env": {
        "CARRIERSCRUB_AUTH": "Bearer cs_live_YOUR_KEY"
      }
    }
  }
}

Keep Authorization:${CARRIERSCRUB_AUTH} exactly as written, with no space after the colon. On some systems Claude Desktop mangles spaces inside args, so the space belongs in the env value instead.

Other clients

Any MCP client that supports Streamable HTTP and lets you set a request header will work. Give it the server URL and the Authorization header from the table above. The server is stateless: every request is one JSON-RPC message sent as a POST, with a JSON reply and no session to keep.

To test a key without an assistant, send an initialize request. A working key returns "serverInfo" with the name carrierscrub:

curl -s https://carrierscrub.com/mcp \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}'

Tools

lookup_carrier

Checks one carrier. The query argument takes a USDOT number such as USDOT 8893375 or just 8893375, or an MC number such as MC 123456. Bare digits are read as a USDOT number.

It returns the same result as a lookup in the app:

• The verdict, GO, CAUTION or STOP, with dated reason codes. Each code states a fact FMCSA published, not a conclusion about the company.
• The carrier's legal name and location.
• record_source and record_as_of: which FMCSA record the verdict used and that record's date. A legacy record comes from a file FMCSA stopped updating on 14 May 2026.
• freshness: how current the answer is. source is live when FMCSA was read for this request and stored for a saved answer; stale is true when part of it is more than a day old; live_check_failed is true when FMCSA did not answer and the saved answer was used instead. A stored answer still has FMCSA's out-of-service orders and current authority, insurance and suspension notices checked on their own.
• data_as_of: when CarrierScrub read that record.
• authority_granted_on and authority_reinstated_on: when FMCSA first granted the carrier's motor carrier authority and when it was last reinstated, from FMCSA's authority history (null when none is on file). They are facts beside the verdict, not reasons: a new authority is not a bad one.
• contact_check: what an independent verification service reports about the phone number and physical address on the carrier's FMCSA registration — whether the number is valid and in service, its line type, and whether the address is a real postal address, a PO box or a PMB. Each item is a fact with a tone of attention or info; none is a verdict, and nothing in it changes the verdict. The registered number appears by its last four digits only. Results are kept for 30 days per carrier, and a brokerage can run 50 uncached checks a day; past that, status is limit and the lookup is otherwise unchanged.

search_carriers

Finds carriers whose legal name or DBA (doing business as) name starts with the text given, so the assistant can get a USDOT number to check. The name argument needs at least three characters. It returns up to 25 legal-name matches and then up to 10 DBA matches, each with the USDOT number, legal name, city, state, whether the carrier has active operating authority, whether it holds broker authority only, and which name matched. A match is not a verdict; the assistant should run lookup_carrier on the one you mean.

get_fmcsa_activity

Says how many carriers’ FMCSA records changed in a week or on one day: operating authorities that went inactive (broker authorities counted separately), new authority applications, authorities granted or reinstated, liability insurance, bonds and cargo insurance that went off file, carriers flagged for returned mail, and carriers whose phone, email or address changed. These are the numbers on the news page and the weekly FMCSA report, counted from FMCSA’s own data, and no carrier is named.

• period is week (the default: the latest complete Monday-to-Sunday week) or day (the latest day with counts).
• date, written YYYY-MM-DD, picks a day, or for a week any day in it. Counts begin on 6 October 2026.
• It returns a dated summary to quote, the counts, a week’s days and its change against the week before (only between two complete weeks), the period’s headlines for brokers with links to their publishers, the page to cite, and where the numbers come from. The sentence under each headline is CarrierScrub’s, written with AI.
• It doesn’t count toward the daily limit. The same answer is public at GET https://carrierscrub.com/v1/fmcsa-activity.

Limits and errors

• Daily limit. Your brokerage's API allows 100 requests a day, or 1,000 on the Agency plan, shared with any direct API use, and resets at 00:00 UTC. Each lookup_carrier call counts once. Connecting and listing tools don't count.
• Search limit. search_carriers is capped at 300 searches a day from one network address, the same as name search on the website.
• Refusals the assistant can read. When a check can't be completed, such as no carrier for that MC number, the daily limit reached, or no free lookups or credits left this month, the tool returns CarrierScrub's message as its result. The assistant sees it and can tell you what happened. A check that can't be completed is never charged.

Problems with the connection itself come back as HTTP errors before any tool runs:

Keeping access safe

• Review connected apps. Admin lists every app connected by sign-in, who approved it and when it was last used. Disconnecting one stops it immediately. Signing out of CarrierScrub in a browser does not disconnect it.
• One key per assistant. Name each one. The API keys list in Admin shows when each key was last used, and the audit log names the key on every check it runs.
• Unused keys stop working. A key that goes 60 days without a successful call stops working and shows as expired in Admin. A key in regular use never expires. If an assistant starts getting 401 after a long break, make it a new key.
• Treat the config file like a password. Most assistants store the key in a settings file as plain text. Use the environment-variable or prompt options above where your client has them, and never commit a key to a repository.
• Revoke when in doubt. Revoking a key in Admin stops it immediately. Do it when someone leaves, a laptop is lost, or a key may have been shared.

Setup questions go to CarrierScrub support.