# PerilScore (full)

> Catastrophe risk SaaS for US properties. Built for insurance agents,
> underwriters, and now AI agents. The core "score this address" operation
> is exposed via REST, MCP, and a live dual-auth connector at /mcp.

## What it does

Given a US address, PerilScore returns:

- **Six natural-peril scores** (0-10 scale) for hurricane, wildfire, hail,
  flood, earthquake, and tornado — with the top contributing risk factors for
  each.
- **Crime peril** (0-10 scale), surfaced as a standalone peril sourced from
  national reporting data. Crime is shown alongside the cat perils but is
  **excluded** from the headline overall property risk number (which reflects
  catastrophe perils only).
- **Nearest fire station** (name, distance, station type, driving time).
- **Protection score** (`fire_protection_score`) — proprietary 1-10 score from fire-station
  characteristics; lower is better. Bands: Strong (1-3), Adequate (4-6),
  Limited (7-8), Remote (9-10).
- **Report URL** at /r/{public_id}/. Public for ChatGPT-channel demos,
  embed-widget partner scores, and anonymous-tier scores; private (auth
  required) for authenticated API/connector/dashboard scores.
- **Premium (explicit protected tool):** holistic Overall Property Score,
  normalized property and construction data, COPE, an indicative structure
  replacement-cost (RCV) range, permit signals where available, imagery
  metadata, an AI-assisted underwriting summary, and billing metadata.

## Endpoints

### REST

```
GET https://app.perilscore.com/api/v1/score/?address=123+Main+St,+Miami,+FL+33101
Authorization: Bearer ps_api_<your_key>
```

REST returns a full report with `formatted_address`, `perils[]`,
`fire_station`, `fire_protection_score`, overall risk, `tier`, `public_id`,
`report_url`, and normalized `property`, `cope`, permit data, and
AI-summary fields where available. A fresh report may consume one credit; a
recent matching score may be reused. REST does not accept a caller-supplied
idempotency key, so do not automatically retry an ambiguous timeout. Prefer
canonical MCP `build_underwriting_report` when replay-safe billing and explicit
charge/reuse metadata matter. If an assessment is unavailable, its billing
status is unknown and it is not safe to retry automatically; inspect report
history and billing before retrying.

### MCP (Streamable HTTP, JSON-RPC 2.0)

- Canonical MCP: `POST https://app.perilscore.com/mcp` — mixed auth, 10 tools. Discovery, MCP App
  resources, and free `score_address` are public; premium/account tools use
  OAuth 2.1 or Bearer `ps_api_*`.
- Legacy MCP: `POST https://app.perilscore.com/api/mcp/` — retained for compatibility.
- Anonymous demo: `POST https://app.perilscore.com/claude/mcp/` — perils + fire station + Protection score.
- ChatGPT App: `POST https://app.perilscore.com/chatgpt/mcp` — wrapped in OpenAI Apps SDK.

Protocol version: `2025-11-25` (Anthropic-protected MCP).

### OAuth-protected connector (live)

- AS metadata: `https://app.perilscore.com/.well-known/oauth-authorization-server`
- Protected resource: `https://app.perilscore.com/.well-known/oauth-protected-resource`
- Connector endpoint: `https://app.perilscore.com/mcp` — mixed-auth 10-tool surface.

Hosted Claude uses Anthropic-held OAuth client credentials. Claude Code uses
the trusted CIMD client `https://claude.ai/oauth/claude-code-client-metadata`.
Cursor uses the pre-registered public client `perilscore-cursor-mcp`. Grok
Build uses the pre-registered public client `perilscore-grok-mcp`. Both use
S256 PKCE with no client secret. Grok on the web can add the same endpoint as
a Custom connector. A PerilScore organization API key remains available for
service and generic MCP clients.

## Example prompts

1. "Use the free PerilScore tool for 123 Main St, Miami, FL 33101."
2. "Build a premium underwriting report for 200 East Las Olas Blvd, Fort
   Lauderdale, FL using retry key las-olas-review-001. Show the RCV assumptions,
   permit availability, and billing result."
3. "Use this report as decision-support evidence and identify fields a qualified
   insurance professional should verify before applying our eligibility rules."

## Get an API key

Programmatic signup: `POST https://app.perilscore.com/api/v1/signup/` with `{"email": "you@example.com"}`
— returns a magic link; then visit `https://app.perilscore.com/developers/api/` to copy your key.

Or sign in at https://app.perilscore.com/auth/signin/ → developer dashboard → generate API key.
The public `score_address` tool is permanently free and non-billable. The
explicit `build_underwriting_report` tool requires authentication, available
organization report capacity (including trial credits), and an idempotency key;
a fresh report may consume one credit.

## Discovery + MCP manifest

- https://app.perilscore.com/.well-known/mcp.json — MCP server manifest
- https://app.perilscore.com/.well-known/ai-plugin.json — legacy ChatGPT plugin spec
- https://app.perilscore.com/openapi.json — OpenAPI 3.1 spec for REST
- https://app.perilscore.com/developers/agent-kit/SKILL.md — maintained integration workflow
- https://app.perilscore.com/developers/agent-kit/build-with-perilscore.zip — installable Agent Kit

## Support

- Email: info@perilscore.com
- Connector reviewers: connectors@perilscore.com
- Privacy: https://app.perilscore.com/privacy/
- Terms: https://app.perilscore.com/terms/