convez.ai
MCP Server
toddshaner

insurancexdate-mcp

toddshaner/insurancexdate-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

TypeScript MCP server (.mcpb Desktop Extension) for the InsuranceXDate workers'-comp prospect database and SERFF rate-filing API. 7 tools, full upstream schema coverage, production-grade error handling. Unofficial third-party client.

Instalação

$npx convez-ai toddshaner/insurancexdate-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
2
Acompanhando
0
Saúde
57%
Último commit
há 3 meses
Versão
v1.5.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

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:

ToolCostPurpose
searchFreeWorkers'-comp prospect search by state, renewal window, class, SIC, industry, county, carriers, carrier groups, agents, PEO providers, premium range, mod range, employee band (0-9), policy options (AR / multi-state / PEO), additional-data filters (BENEFITS / DOT / NPO / OSHA / PEO)
matchFreeFind a specific business by at least one of name[] / fein / phone / address[], optionally scoped by state. Routes to /api2/Match. No additional service required per XDate support; fuzzy lookup returns the highest-score match
filterFreeLook up valid filter values: carriers, carrier groups, classes, SIC codes, industries, counties, agents, PEO providers. Policy options and additional-data options are fixed search enums, not filter lookups
company_details$0.25Full account detail by UID: summary, details (~77 fields incl. premium, payroll, mod, signalScore, hazardGroup), carrier_history[] (per-policy-term rows, multi-year multi-state), _meta field docs. contacts/altloc no longer returned upstream (see Upstream response notes)
talkpoints$0.10Prospecting talking points + percentile flags by UID
serff_search$0.05SERFF rate-filing search by carrier_naic (integer) + state + insurance type (TOI) + severity. Uses the upstream's documented parameter names
serff_filing$0.10Full 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`
        │     translates MCP-style param names (premfrom/premto/modfrom/
        │     modto/limit/offset) to REST equivalents (fromprem/toprem/
        │     frommod/tomod/pagelimit/pageon)
        │
        ├──► /api2/Match    (REST)   for `match`
        │     find-by-name endpoint (the upstream MCP's `name` param on
        │     `search` is silently dropped at REST, so `/Match` is the
        │     correct route for find-by-identifier lookups)
        │
        └──► /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 and match return 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 (also accepts true / yes / on / enabled, case-insensitive) in env to short-circuit company_details, talkpoints, serff_search, serff_filing with isError responses. Any other non-empty value leaves paid tools enabled and logs a startup warning to stderr. 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.

⚠️ Windows Store / MSIX build of Claude Desktop: Option A may not work. If Claude Desktop was installed from the Microsoft Store (MSIX, under C:\Program Files\WindowsApps\Claude_*), the "Install Extension" dialog can silently fail to fire — the file picker closes and nothing installs, with no error. That build also spawns MCP servers with a stripped environment that does not inherit your user variables. Use the config-file path instead:

  1. Build from source (Option D) so you have server\dist\index.js.
  2. Add an mcpServers entry to %APPDATA%\Claude\claude_desktop_config.json pointing node at that file. Put the key in the entry's env block — on MSIX the server will not pick up a system-set INSURANCEXDATE_API_KEY on its own:
    {
      "mcpServers": {
        "insurancexdate": {
          "command": "node",
          "args": ["C:\\path\\to\\insurancexdate-mcp\\server\\dist\\index.js"],
          "env": { "INSURANCEXDATE_API_KEY": "your-key-here" }
        }
      }
    }
    
  3. Fully quit Claude Desktop (system tray → Quit, not just close the window), then relaunch. Note: Claude rewrites this file from memory, so if an edit seems to revert, make it while the app is fully quit.

To keep the key out of plaintext config, point command at a small wrapper script (.cmd) that reads INSURANCEXDATE_API_KEY from your OS credential store / HKCU\Environment and then launches node — the server reads the key from its own environment, so the wrapper only needs to set it before exec. Verify after launch: the tools register under the lowercase prefix mcp__insurancexdate__* (from the config key), not the .mcpb display name.

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")

The severity filter is exact-match, not a threshold: severity="4" returns only severity-4 filings, not 4 and 5. To capture both 4 and 5 (the broker-attack range), call twice and merge response-side, or omit severity entirely and filter the response client-side.

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.

Upstream response notes (observed 2026-06-12)

XDate revises its response surfaces without versioning or notice. Three things to know as of the Q2 2026 platform release:

  • company_details envelope changed. The response is now { summary, user_status, details, carrier_history, _meta } (previously { status, data: { details, contacts, carriers, altloc } }). carriers became carrier_history (full per-policy-term rows, each carrying the same ~77 fields as details — hundreds of rows for multi-state operators, easily 1-2 MB). contacts and altloc are no longer returned. New fields include signalScore, hazardGroup, and a _meta block documenting each field. The wrapper passes all of this through unmodified by design.
  • Free-tier field masking on search/match results. name, fein, location, expyear, carrier, and carriergroup return the literal string "available" — present-but-withheld markers, not values. Don't treat "available" as data; pull company_details for real values.
  • The Q2 2026 DOT and NPO datasets are platform-UI only. DOT safety inspections, crashes, cargo types, and NPO IRS-990 financials announced in June 2026 do not appear in any API response. The addloptions NPO flag does filter server-side, but it matches companies with linked 990 data — including for-profit companies with affiliated foundations — and search results carry no per-record npo flag.

SERFF response notes

serff_search and serff_filing route to the upstream MCP and return XDate's structured shape of SERFF rate filings. A few things worth knowing before you build against the response:

Sentiment language is policyholder-perspective, not broker-perspective

The sentiment field uses bad / good / neutral from the policyholder's point of view. The XRate web UI shows the same data with broker-perspective labels.

API sentimentXRate UI labelMeaningBroker-side action
badOffensiveUnfavorable to policyholders (rate up, coverage cut)Attack opportunity (filing carrier's renewal is exposed)
goodDefensiveFavorable to policyholders (rate down, expanded coverage)Retention play (don't displace a filing helping the insured)
neutralNeutralAdministrative, insignificant, or new programWatch only

A consumer reading sentiment: "good" and assuming it's good for the broker reaches the wrong conclusion. Document this translation in any client code that surfaces SERFF data to brokers.

severity_types observed values

Filings can carry multiple. Use as a client-side post-fetch filter:

RATE_CHANGE, LCM_ADJUSTMENT (WC-specific repricing), TIERING_REVISION (winners/losers within a carrier book), COVERAGE_MODIFICATION, UNDERWRITING_REVISION (eligibility shifts), ADMINISTRATIVE (typically skip), NEW_PROGRAM, MARKET_EXIT (carrier exiting line/state/segment), DIVIDEND_PLAN.

What serff_filing returns vs. what's NOT in the response

serff_filing surfaces structured fields suitable for programmatic triage at scale, but is curated rather than exhaustive. Verified empirically against filing 21434 (Berkley Casualty IL WC, public SERFF tracking BNIC-134422662):

Structured and reliable:

  • carrier_names + naic_codes — full per-paper list when a filing covers a multi-paper carrier group
  • disproportionately_affected — text array describing the harmed papers and class codes (e.g., "Carolina Casualty Insurance Company (CCIC) facing a 22.4% increase"); explicit % values for the harmed direction
  • affected_naics — array of NAICS sector codes hit by the filing
  • actuarial_justifications — short summary bullets of the carrier's stated reasoning
  • key_coverage_changes — coverage form / endorsement changes
  • narrative — pre-shaped markdown text (multiple labeled sections, written for downstream broker-attack use cases, not actuarial prose)

NOT in the response (manual XRate UI or SERFF Filing Access required):

  • Per-tier % impacts for favorable-direction papers. The response itemizes the harmed direction; the full per-tier table is UI-only. (For filing 21434 verified 2026-04-26: API surfaced CCIC +22.4% and BCC +18.1%; UI also exposes KRIC +6.8%, StarNet -0.6%, MECC -12.2%.)
  • Per-paper Loss Cost Multiplier (LCM) values. UI shows the new LCM alongside the % impact — the underlying repricing mechanism. API's actuarial_justifications references LCM alignment qualitatively but doesn't expose values per paper.
  • Specific reallocation movement rates. Carriers using a multi-paper reallocation strategy (move accounts between papers to mask the headline rate impact) disclose specific transition % values in the UI (e.g., "45% of CCIC renewals to BCC, 30% of BCC renewals to KRIC"). API narrative references "reallocation" qualitatively but doesn't expose these as structured fields.
  • Per-paper policyholder counts. UI breaks the affected-policyholder count down by paper. API gives total policyholders but not the per-paper distribution.
  • Full filing memorandum / actuarial exhibits. Only the 3-bullet actuarial_justifications summary is in the response.
  • Parent carrier-group identifier. The response carries per-paper NAICs but no group-level ID; group-level lookups require a separate filter call enumerating groups.
  • Class codes as a structured array. Class codes appear inside disproportionately_affected as unstructured text — regex-parseable, but not a typed field.

If you're building an automated pipeline that depends on the full per-tier table or actuarial exhibits, plan for a manual SERFF Filing Access lookup as a final step. The API gets you ~3.5 of 4 things you'd want for programmatic triage; the last 0.5 still requires a manual read.

NAICS code formatting

affected_naics returns 3-digit raw integers ([238, 482, 485, 711]). The XRate UI displays the same codes 4-digit zero-padded (0238, 0482, etc.). Same codes, different formats — normalize before comparison if you parse both surfaces.

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
npm test                    # no-network smoke test: tool registration, search schema shape, version consistency (same gate CI runs)
node dist/index.js          # manual stdio poke (set INSURANCEXDATE_API_KEY in env)
cd ..
npx -y @anthropic-ai/mcpb pack .

Version bumps touch three files — server/src/index.ts (serverInfo), server/package.json (use npm version in server/ so the lockfile follows), and manifest.json — and the smoke test asserts all three agree, so a missed one fails npm test rather than shipping.

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 .

Diff every param name and type against the wrapper's zod schemas. Mismatches in name or type at the upstream surface silently as "filter not applied" symptoms — the call succeeds, the param is dropped, and the response is the unfiltered universe. The CHANGELOG documents two cases this audit caught (serff_search's naic/type vs. upstream carrier_naic/insurance_type, and search's naicslist advertised but no-op upstream).

When integrating against a 3rd-party API where you have an alternative source of truth (a public registry, a documented spec, a UI you can verify against), cross-validate at least one record end-to-end. For SERFF, public SERFF Filing Access (free) carries the same filing data and the API's disposition_date should match exactly. Drift between the two is itself a signal worth investigating.

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.

Ver o original no GitHub

Bom para

Relacionados