InsuranceXDate MCP

A TypeScript Model Context Protocol server that wraps the InsuranceXDate workers'-comp prospect database and SERFF rate-filing API. Works with any MCP client — Claude Desktop, Cursor, Continue, Zed, Cline, or a custom client built on the MCP SDK.

Unofficial third-party client. Not affiliated with InsuranceXDate. MIT licensed. Personal project — PRs welcome but no SLA on response times.

Built on @modelcontextprotocol/sdk v1.29, Node 20+. Ships as both a pre-packaged Anthropic .mcpb Desktop Extension for one-click install on Claude Desktop, and as plain Node source you can wire into any other MCP client's config.

What it does

Exposes seven tools to MCP clients:

| Tool | Cost | Purpose | |---|---|---| | search | Free | Workers'-comp prospect search by state, renewal window, class, SIC, industry, county, carriers, agents, premium range, mod range, employee band (0-9), policy options (AR / multi-state / PEO), additional-data filters (BENEFITS / DOT / NPO / OSHA / PEO) | | match | Free | Find a specific business by state + name[] + optional address[] / fein / phone. Routes to /api2/Match. Some subscription tiers do not include access | | filter | Free | Look up valid filter values: carriers, carrier groups, classes, SIC codes, counties, agents, PEO providers, policy options, additional-data options | | company_details | $0.25 | Full account detail by UID: carrier history, mod / LCM, premium, payroll, contacts, multi-state policy footprint | | talkpoints | $0.10 | Prospecting talking points + percentile flags by UID | | serff_search | $0.05 | SERFF rate-filing search by carrier_naic (integer) + state + insurance type (TOI) + severity. v1.1.2+ uses the upstream's documented parameter names | | serff_filing | $0.10 | Full SERFF filing detail by integer filing_id |

Architecture

MCP client (Claude Desktop, Cursor, Continue, Zed, custom...)
        │  (stdio JSON-RPC)
        ▼
  InsuranceXDate MCP server (this repo)
        │
        ├──► /api2/Search   (REST)   for `search`, `match`
        │     translates MCP-style param names (premfrom/premto/modfrom/
        │     modto/limit/offset) to REST equivalents (fromprem/toprem/
        │     frommod/tomod/pagelimit/pageon)
        │
        └──► /api2/McpData  (MCP)    for `filter`, `company_details`,
              `talkpoints`, `serff_search`, `serff_filing`
              passes parameters through using the upstream MCP's
              documented schema (carrier_naic / insurance_type /
              severity for serff_search)

The split exists because the upstream MCP at /api2/McpData and the REST endpoint at /api2/Search use different parameter naming conventions and have different filter behavior on prospect search. This wrapper bridges both surfaces with a consistent client-facing schema.

Production-grade defaults

• HTTP timeout: 30s via AbortSignal.timeout() so slow upstream calls surface as clean errors instead of silent hangs
• HTTP error handling: non-2xx responses throw with status + body excerpt. Wrapper returns isError: true MCP results rather than wrapping error bodies as success
• structuredContent: search returns both content (text JSON fallback) and typed structuredContent so LLMs can reason over records without re-parsing
• URL-decode for UIDs: company UIDs from /api2/Search come URL-encoded (%2B, %2F); wrapper decodes before forwarding to upstream MCP for paid lookups, which expect raw +//
• Schema validation: zod-validated input on every tool (state codes uppercase regex, dates MM-DD regex, premium/mod numeric, employee band 0-9, addloptions/policyoptions enum)
• Paid-tool gate: set XDATE_DISABLE_PAID=1 in env to short-circuit company_details, talkpoints, serff_search, serff_filing with isError responses. Defense-in-depth for environments where you want to whitelist free tools only
• Sensitive credential storage: when installed via .mcpb on Claude Desktop, the API key flows through user_config.api_key with "sensitive": true and is stored in the OS keychain (Windows Credential Manager / macOS Keychain). On other MCP clients the server reads INSURANCEXDATE_API_KEY from process.env, so use whatever secret-handling pattern your client supports (env-var injection, secret store, etc.) — never hard-code keys in JSON config files committed to source control

Install

The server runs as a Node.js process speaking MCP over stdio. Any MCP client can launch it. Pick the install path that matches your client.

Prerequisites (all paths)

• Node.js 20+ (only required for Options B / C / D — Option A bundles its own runtime)
• An InsuranceXDate API key from your account's Settings → API / MCP page

Option A: Claude Desktop (one-click .mcpb)

1. Download the .mcpb from the latest Release
2. Double-click the .mcpb file → Claude Desktop opens an install dialog
3. Click Install
4. Paste your InsuranceXDate API key when prompted

The key is stored in the OS keychain via the manifest's user_config.api_key with "sensitive": true. No Developer Mode toggle required — .mcpb is designed for one-click end-user install.

Option B: Cursor

Build from source (see Option D), then add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "insurancexdate": {
      "command": "node",
      "args": ["/absolute/path/to/insurancexdate-mcp/server/dist/index.js"],
      "env": {
        "INSURANCEXDATE_API_KEY": "your-key-here"
      }
    }
  }
}

For team setups, store the key in a secret store and inject via Cursor's env handling rather than committing the key.

Option C: Continue, Zed, Cline, or any other MCP client with a config file

Same shape as Option B — point the client's MCP config at server/dist/index.js and pass INSURANCEXDATE_API_KEY via the env block. Consult your client's MCP-config docs for the exact file path and JSON schema (most converge on something close to Cursor's format).

For a custom client (Python, TypeScript, Go) launching the server directly, you only need:

INSURANCEXDATE_API_KEY=your-key-here node /path/to/server/dist/index.js

The server speaks standard MCP JSON-RPC on stdio. Anything that follows the protocol works.

Option D: Build from source

git clone https://github.com/toddshaner/insurancexdate-mcp.git
cd insurancexdate-mcp/server
npm install
npm run build               # tsc emits server/dist/*.js (noEmitOnError prevents broken builds)

server/dist/index.js is the entry point for Options B / C and any custom client.

To repack the .mcpb for Claude Desktop after a source change:

cd ..                       # back to repo root
npx -y @anthropic-ai/mcpb pack .

For a slimmer .mcpb, run npm prune --omit=dev after build to strip TypeScript and @types/* from node_modules — .mcpbignore covers them anyway, but pruning is cleaner.

Usage examples

After install, in any MCP-enabled chat client:

Discover IL workers'-comp prospects, $250K+ annual premium, renewing in the next 60-120 days, with size-signal flags pre-filtered server-side:

search(
  statelist=["IL"],
  fromdate="06-24",
  todate="08-23",
  premfrom=250000,
  addloptions=["BENEFITS","DOT","OSHA"],
  limit=50
)

Find a specific company by name + state:

match(state="PA", name=["Acme Logistics", "Acme Logistics Inc"])

Pull rate filings for Berkley Casualty in IL, workers' comp only, severity 4+:

serff_search(carrier_naic=15911, state="IL", insurance_type="16.0", severity="4")

State-data coverage

InsuranceXDate's data depth varies by state. Some filters only have data to operate on in specific states:

• Premium data (premfrom / premto): CO, GA, IL, NV, NJ, OK, TX, VT (8 states)
• Mod data (modfrom / modto): DE, MA, MN, NJ, NY, NC, OH, PA (8 states)
• WC class code data (classlist): 21 states (CA, CO, CT, DE, FL, GA, IL, KY, ME, MD, NV, NH, NJ, OH, OK, OR, PA, SC, TX, VT, VA)
• SIC codes, employee count, carrier, sales (most filters): 44 states (broadest)

Outside these footprints the corresponding filters have no data to operate on. This is upstream data availability, not a wrapper limitation.

Development

Project structure

.
├── manifest.json             # .mcpb manifest (Node type, user_config keychain, 7 tools)
├── .mcpbignore               # excludes src/, devDeps, source maps from the bundle
├── LICENSE                   # MIT
├── README.md                 # this file
├── CHANGELOG.md              # version history
└── server/
    ├── package.json          # @modelcontextprotocol/sdk + zod runtime; tsc + types as devDeps
    ├── tsconfig.json         # strict + noEmitOnError
    └── src/
        ├── index.ts          # MCP server entry — registers tools, stdio transport
        ├── xdate-client.ts   # REST + MCP HTTP clients with param translation, URL decoding, timeout, error handling
        └── tools.ts          # Tool zod schemas, handler factory, paid-tool gate

Build, test, pack

cd server
npm install
npm run build               # tsc with noEmitOnError; broken builds fail fast
node dist/index.js          # smoke test stdio (set INSURANCEXDATE_API_KEY in env)
cd ..
npx -y @anthropic-ai/mcpb pack .

Schema audit pattern

When adding or modifying a tool, validate the wrapper's schema against the upstream by curling tools/list directly:

curl -s -X POST https://www.insurancexdate.com/api2/McpData \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq .

The CHANGELOG documents how this audit caught two parameter-name mismatches (one in serff_search, one in search) that were previously surfacing as "filter not applied" symptoms.

Acknowledgments

Built against the InsuranceXDate API. Their public OpenAPI spec is at https://insurancexdate.stoplight.io/docs/insurancexdate/. Reference architecture validated alongside the openbnb-org/mcp-server-airbnb MCPB install pattern.

License

MIT — see LICENSE.