MCP Server

The MCP Server (apps/mcp, oi-sys-mcp) is a Cloudflare Worker that exposes OpenInsure’s data and operations as Model Context Protocol (MCP) tools. It bridges Claude and other LLM clients directly to live insurance data — policies, claims, submissions, ratings, and more.

Endpoint

Environment	URL
Production	`https://mcp.openinsure.dev/mcp`
Local dev	`http://localhost:8788/mcp`

Architecture

LLM Client (Claude Desktop / Claude.ai)
  └─► MCP Server (oi-sys-mcp)
        └─► @openinsure/agents
              └─► API Worker (oi-sys-api)
                    └─► PlanetScale (Hyperdrive)

The MCP server is a thin adapter. All business logic lives in @openinsure/agents — the MCP layer only handles protocol negotiation (tool listing, call dispatch, streaming) and passes through to the agent framework.

Available Tools

Submissions

Tool	Description
`list_submissions`	List submissions with optional status filter (`new`, `quoted`, `bound`, `declined`)
`get_submission`	Full submission detail by ID
`create_submission`	Create a new submission from structured ACORD data
`analyze_submission`	AI risk analysis — appetite score, referral reasons, suggested premium
`rate_submission`	Run the rating engine against a submission and return premium breakdown

Policies

Tool	Description
`list_policies`	List active policies with optional program/producer filter
`get_policy`	Policy detail including coverages, endorsements, and billing status
`get_policy_documents`	List generated documents for a policy (dec page, binder, jacket)

Claims

Tool	Description
`list_claims`	List claims with status, reserve, and adjuster filters
`get_claim`	Full claim detail including reserve history and payments
`get_claim_status`	Current claim status and pending actions
`file_fnol`	Submit a First Notice of Loss for an existing policy
`update_reserve`	Update loss reserve with reason code

Producers

Tool	Description
`list_producers`	List producers with license status and appointment states
`get_producer`	Producer profile with commission rates and performance metrics
`check_producer_license`	Validate producer license for a specific state and line of business

Analytics

Tool	Description
`get_portfolio_kpis`	GWP, loss ratio, combined ratio, submission pipeline metrics
`get_loss_ratio`	Loss ratio breakdown by LOB, state, and producer
`get_bordereaux_summary`	Bordereaux submission status and premium totals

Compliance

Tool	Description
`check_sanctions`	Run OFAC/international sanctions screen for a name
`get_filing_deadlines`	Upcoming state filing deadlines and overdue status
`get_compliance_summary`	Expiring licenses, filings due, and urgent compliance items

Resources

The MCP server exposes these resources (readable via MCP resource:// URIs):

Resource	Description
`openinsure://policies/{id}`	Live policy record
`openinsure://claims/{id}`	Live claim record
`openinsure://submissions/{id}`	Live submission record
`openinsure://producers/{id}`	Producer profile
`openinsure://programs/{id}`	Program configuration

Setup: Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openinsure": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client-sse", "https://mcp.openinsure.dev/mcp"],
      "env": {
        "OPENINSURE_TOKEN": "<your-system-jwt>"
      }
    }
  }
}

Setup: Claude.ai

The MCP server is registered as a remote MCP connector in the claude.ai workspace settings. No local client required — Claude connects directly to https://mcp.openinsure.dev/mcp.

Authentication

All MCP tool calls pass the token from the client environment. Generate a system role token:

# From the API worker
curl -X POST https://api.openinsure.dev/v1/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"name": "claude-mcp", "role": "system"}'

Or use the Admin Portal → API Keys page.

Development

# Run MCP server locally
pnpm --filter @openinsure/mcp dev
# Listening on http://localhost:8788

# Deploy to Cloudflare
pnpm --filter @openinsure/mcp deploy

The dev server proxies agent calls to http://localhost:8787 (the API worker). Run both workers simultaneously during development.

Extending

Add new tools in @openinsure/agents — the MCP server auto-discovers any tool exported from the agent registry. Follow the pattern in packages/agents/src/tools/:

export const myTool = {
  name: 'my_tool',
  description: 'What this tool does',
  inputSchema: z.object({ id: z.string() }),
  async execute(input, context) {
    // implementation
  },
};

AI Agents

Durable Object agents, orchestration, and Langfuse observability.

API Reference

Full REST API documentation.