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.

note

The MCP server enforces the same JWT authorization as the API. All tool calls require a valid Authorization: Bearer <token> header with an appropriate role. The system role is recommended for AI agent integrations.

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.