Connect an AI assistant to CarrierScrub

Before you start

1. Your brokerage needs the Agency plan. Keys stop working if the plan lapses, and start again when it is active.
2. An owner or admin opens Admin, then API keys, and clicks New key.
3. Name the key after the assistant and the person using it, for example “Claude Code, Dana”. One key per assistant means 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 every example below, replace cs_live_YOUR_KEY with your key.

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.”

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

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.
• data_as_of: when CarrierScrub read that record.

search_carriers

Finds carriers by legal name, so the assistant can get a USDOT number to check. The name argument needs at least three characters. It returns up to 25 matches with the USDOT number, legal name, city, state, whether the carrier has active operating authority, and whether it holds broker authority only. A match is not a verdict; the assistant should run lookup_carrier on the one you mean.

Limits and errors

• Daily limit. Your brokerage's API allows 1,000 requests a day, 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 or the daily limit reached, 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 keys safe

• 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.
• 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.