{
  "name": "perilscore",
  "title": "PerilScore \u2014 Property Catastrophe Risk",
  "version": "1.0.0",
  "description": "Property risk, RCV, and permit intelligence for US properties. The public score is free; an explicit protected tool builds a premium report with normalized property/construction data, COPE, indicative replacement cost, permit signals, imagery, AI-assisted findings, and transparent billing metadata. PerilScore supports qualified insurance professionals and does not make coverage decisions.",
  "mcp_protocol_versions": [
    "2025-11-25",
    "2025-03-26"
  ],
  "transports": [
    "streamable-http"
  ],
  "endpoints": [
    {
      "url": "https://app.perilscore.com/mcp",
      "transport": "streamable-http",
      "auth": "oauth2-or-bearer-api-key",
      "protocol_version": "2025-11-25",
      "description": "Canonical mixed-auth MCP connector. initialize, tools/list, MCP App resources, and score_address are public. score_address is always free and non-billable. Protected tools use OAuth 2.1 or a Bearer ps_api_* organization key. The explicit build_underwriting_report tool requires an idempotency key and may charge one credit.",
      "auth_behavior": {
        "mode": "mixed-lazy-auth",
        "public_methods": [
          "initialize",
          "tools/list",
          "resources/list",
          "resources/read"
        ],
        "public_tools": [
          "score_address"
        ],
        "protected_tools": [
          "build_underwriting_report",
          "get_score",
          "retry_report_enrichment",
          "list_scores",
          "get_share_score_url",
          "get_report_pdf_url",
          "get_account_credits",
          "export_score_factors",
          "get_acord_url"
        ]
      },
      "tool_count": 10,
      "tools": [
        {
          "name": "score_address",
          "title": "Get a Free Property Risk Score",
          "description": "Free, anonymous-capable address lookup for US catastrophe peril scores, nearby fire-station context, and Fire Protection Score. This tool never consumes a PerilScore credit and never returns premium property, RCV, permit, imagery, or AI underwriting data. This endpoint accepts exactly one US property address. Bulk-shaped arguments, including lists, uploaded CSV or XLSX data, tables, schedules of values (SOVs), portfolios, and books of business, are rejected before preview quota reservation or scoring. Authenticated bulk scoring is available through the PerilScore SaaS SOV workflow when report capacity is available. This endpoint never creates a premium report or invokes premium enrichment. PerilScore provides property-risk evidence, not a coverage decision. A qualified insurance professional must verify the data and review any customer-authored eligibility, referral, inspection, or underwriting rule before a decision affecting an applicant, insured, or policyholder is finalized or communicated.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string",
                "maxLength": 500,
                "description": "Exactly one complete US property street address. One-line and ordinary multiline addresses, including unit numbers and ZIP+4 codes, are accepted; lists and tables are not."
              }
            },
            "required": [
              "address"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": true,
            "title": "Get a Free Property Risk Score"
          },
          "_meta": {
            "ui": {
              "resourceUri": "ui://perilscore/score-card-v2.html",
              "visibility": [
                "model",
                "app"
              ]
            }
          }
        },
        {
          "name": "build_underwriting_report",
          "title": "Build a Premium Underwriting Report",
          "description": "Build or reuse a premium property-intelligence report. A fresh report consumes one PerilScore credit after entitlement is checked; a recent matching report or an idempotent replay is not charged again. Returns normalized property and construction data, COPE, an indicative structure replacement-cost (RCV) range and construction-cost factors, permit signals where available, imagery metadata, the AI-analysis lifecycle status, and an Overall Property Score. For an already-created report, use get_score with the returned premium public_id to refresh persisted results; do not create a second report. That retrieval consumes no credit. RCV is not market value, an appraisal, a contractor bid, or carrier cost-manual certification. Permit coverage varies by jurisdiction. PerilScore provides property-risk evidence, not a coverage decision. A qualified insurance professional must verify the data and review any customer-authored eligibility, referral, inspection, or underwriting rule before a decision affecting an applicant, insured, or policyholder is finalized or communicated.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string",
                "maxLength": 500,
                "description": "Complete US street address."
              },
              "idempotency_key": {
                "type": "string",
                "minLength": 8,
                "maxLength": 128,
                "description": "Required retry key for replay-safe billing. Reuse the same key only for the same address and candidate."
              },
              "property_candidate_key": {
                "type": "string",
                "maxLength": 200,
                "description": "Property key returned after address_selection_required."
              }
            },
            "required": [
              "address",
              "idempotency_key"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": false,
            "destructiveHint": true,
            "idempotentHint": true,
            "openWorldHint": true,
            "title": "Build a Premium Underwriting Report"
          },
          "_meta": {
            "ui": {
              "resourceUri": "ui://perilscore/score-card-v2.html",
              "visibility": [
                "model",
                "app"
              ]
            }
          }
        },
        {
          "name": "get_score",
          "title": "Get an Existing Score",
          "description": "Get an authenticated organization's score by public ID, including stored premium blocks when present. Use the public_id returned by the premium report itself when refreshing it; this does not consume a credit or create a new report. Optional sections return detailed property, COPE, peril factors, replacement cost, paginated permits, imagery observations, underwriting findings, or provenance. compare_to_public_id compares another owned report; replacement_cost_scenario evaluates hypothetical area, construction, or quality assumptions without saving them or changing the score. PerilScore provides property-risk evidence, not a coverage decision. A qualified insurance professional must verify the data and review any customer-authored eligibility, referral, inspection, or underwriting rule before a decision affecting an applicant, insured, or policyholder is finalized or communicated.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "public_id": {
                "type": "string",
                "pattern": "^P-[0-9A-F]{12}$",
                "description": "PerilScore identifier, for example \"P-A1B2C3D4E5F6\"."
              },
              "sections": {
                "type": "array",
                "minItems": 1,
                "maxItems": 9,
                "items": {
                  "type": "string",
                  "enum": [
                    "overview",
                    "property",
                    "cope",
                    "perils",
                    "replacement_cost",
                    "permits",
                    "imagery",
                    "underwriting",
                    "provenance"
                  ]
                },
                "description": "Optional evidence sections; omitted returns the full normalized report overview."
              },
              "permit_cursor": {
                "type": "string",
                "maxLength": 2048,
                "description": "Opaque next_cursor from this report's permits block. Omit for the first page."
              },
              "permit_limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 25,
                "description": "Number of normalized stored permit records to return, up to 25."
              },
              "compare_to_public_id": {
                "type": "string",
                "pattern": "^P-[0-9A-F]{12}$",
                "description": "Another report in the same organization to compare with this report."
              },
              "replacement_cost_scenario": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "area_sqft": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 10000000
                  },
                  "construction_class": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6
                  },
                  "quality_band": {
                    "type": "string",
                    "enum": [
                      "economy",
                      "fair",
                      "average",
                      "good",
                      "excellent"
                    ]
                  }
                },
                "description": "At least one hypothetical RCV assumption. Read-only: never corrects or saves property facts."
              }
            },
            "required": [
              "public_id"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false,
            "title": "Get an Existing Score"
          },
          "_meta": {
            "ui": {
              "resourceUri": "ui://perilscore/score-card-v2.html",
              "visibility": [
                "model",
                "app"
              ]
            }
          }
        },
        {
          "name": "retry_report_enrichment",
          "title": "Retry Missing Property Enrichment",
          "description": "Schedule recovery of missing property records on an already-paid owned report. Returns the same public_id and never consumes another score credit. Active work is reused; known no-match or configuration failures remain explicit. This may update the report's property evidence, derived estimates, and analysis version. Progress is retrieved through read-only get_score. PerilScore provides property-risk evidence, not a coverage decision. A qualified insurance professional must verify the data and review any customer-authored eligibility, referral, inspection, or underwriting rule before a decision affecting an applicant, insured, or policyholder is finalized or communicated.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "public_id": {
                "type": "string",
                "pattern": "^P-[0-9A-F]{12}$",
                "description": "PerilScore identifier, for example \"P-A1B2C3D4E5F6\"."
              }
            },
            "required": [
              "public_id"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": false,
            "destructiveHint": false,
            "idempotentHint": false,
            "openWorldHint": true,
            "title": "Retry Missing Property Enrichment"
          },
          "_meta": {
            "ui": {
              "resourceUri": "ui://perilscore/score-card-v2.html",
              "visibility": [
                "model",
                "app"
              ]
            }
          }
        },
        {
          "name": "list_scores",
          "title": "List Recent Scores",
          "description": "List the authenticated organization's scores, newest first.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "cursor": {
                "type": "string"
              },
              "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100,
                "default": 25
              }
            },
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false,
            "title": "List Recent Scores"
          }
        },
        {
          "name": "get_share_score_url",
          "title": "Get the Score Sharing URL",
          "description": "Return the authenticated PerilScore web URL where a user can review and submit a score-sharing email. This tool never sends email and never accepts a recipient; sharing remains a deliberate human web workflow.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "public_id": {
                "type": "string",
                "pattern": "^P-[0-9A-F]{12}$",
                "description": "PerilScore identifier, for example \"P-A1B2C3D4E5F6\"."
              }
            },
            "required": [
              "public_id"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false,
            "title": "Get the Score Sharing URL"
          }
        },
        {
          "name": "get_report_pdf_url",
          "title": "Get the PDF Report URL",
          "description": "Return the authenticated URL for an owned score's PDF report.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "public_id": {
                "type": "string",
                "pattern": "^P-[0-9A-F]{12}$",
                "description": "PerilScore identifier, for example \"P-A1B2C3D4E5F6\"."
              }
            },
            "required": [
              "public_id"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false,
            "title": "Get the PDF Report URL"
          }
        },
        {
          "name": "get_account_credits",
          "title": "Get Account Credit Balance",
          "description": "Return premium capacity, credit balance, plan, and billing status.",
          "inputSchema": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false,
            "title": "Get Account Credit Balance"
          }
        },
        {
          "name": "export_score_factors",
          "title": "Export Score Factors",
          "description": "Return explainable overall and per-peril factors for an owned score.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "public_id": {
                "type": "string",
                "pattern": "^P-[0-9A-F]{12}$",
                "description": "PerilScore identifier, for example \"P-A1B2C3D4E5F6\"."
              }
            },
            "required": [
              "public_id"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false,
            "title": "Export Score Factors"
          }
        },
        {
          "name": "get_acord_url",
          "title": "Get an ACORD Form URL",
          "description": "Return an authenticated ACORD PDF URL for an owned score. Supports ACORD 140 for every score and ACORD 80 for eligible residential single-family homes and townhouses.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "public_id": {
                "type": "string",
                "pattern": "^P-[0-9A-F]{12}$",
                "description": "PerilScore identifier, for example \"P-A1B2C3D4E5F6\"."
              },
              "form_type": {
                "type": "string",
                "enum": [
                  "140",
                  "80"
                ],
                "default": "140",
                "description": "ACORD form number. Defaults to 140 for backward compatibility. ACORD 80 is available for residential single-family homes and townhouses."
              }
            },
            "required": [
              "public_id"
            ],
            "additionalProperties": false
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "idempotentHint": true,
            "openWorldHint": false,
            "title": "Get an ACORD Form URL"
          }
        }
      ],
      "resources": [
        {
          "uri": "ui://perilscore/score-card-v2.html",
          "mime_type": "text/html;profile=mcp-app",
          "auth": "none"
        }
      ]
    },
    {
      "url": "https://app.perilscore.com/api/mcp/",
      "transport": "streamable-http",
      "auth": "bearer-api-key",
      "protocol_version": "2025-11-25",
      "description": "Legacy MCP endpoint for authenticated, capacity-backed full reports.",
      "tool_count": 1,
      "tools": [
        {
          "name": "get_property_catastrophe_risk_scores",
          "title": "Build a Full Property Assessment",
          "description": "Build or reuse a full property assessment for a US property using the authenticated organization's report capacity. A newly created assessment may consume one report credit; a recent previously billed assessment may be reused without another charge. Returns catastrophe peril scores, Overall Property Score, property and construction data, COPE, an indicative replacement-cost rebuild range (not an appraisal), and AI underwriting summary where available. Check report history and billing before retrying an incomplete request because billing may be pending.  For Florida risks, structured results may include `citizens_wind_only_eligible_area`: approximate/statutory Citizens/FWUA wind-only eligible-area metadata, not a binding eligibility determination.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string",
                "description": "Complete US street address including house number, street name, city, state, and ZIP code. Example: \"123 Main Street, Miami, FL 33139\""
              },
              "property_candidate_key": {
                "type": "string",
                "description": "Smarty property key returned in candidates when address_selection_required is reported."
              }
            },
            "required": [
              "address"
            ]
          },
          "annotations": {
            "readOnlyHint": false,
            "destructiveHint": true,
            "openWorldHint": true,
            "idempotentHint": false
          }
        }
      ]
    },
    {
      "url": "https://app.perilscore.com/claude/mcp/",
      "transport": "streamable-http",
      "auth": "none",
      "protocol_version": "2025-11-25",
      "description": "Anonymous public MCP endpoint for Claude Desktop demos. 50/day per IP, free tier only.",
      "tool_count": 1,
      "tools": [
        {
          "name": "get_property_catastrophe_risk_scores",
          "title": "Get Catastrophe Risk Scores",
          "description": "Look up location-based catastrophe risk scores for a US property. Returns per-peril scores on a 0-10 scale (hurricane, wildfire, hail, flood, earthquake, tornado, crime) with the top contributing factors for each, nearest fire station with driving time, the Protection score (1-10 where lower is better; bands Strong 1-3, Adequate 4-6, Limited 7-8, Remote 9-10), and a deep link to the full interactive report. Crime is surfaced as a standalone peril and is NOT folded into the overall property risk number (which reflects catastrophe perils only). Premium responses add `property.replacement_cost`, an indicative structure rebuild range rather than an appraisal; free responses keep the free shape and omit the premium property block. The full report (linked) adds building construction, COPE data, aerial imagery analysis, and an AI underwriting summary, which are not returned here. All location data is returned in one call. For Florida risks, structured results may include `citizens_wind_only_eligible_area`: approximate/statutory Citizens/FWUA wind-only eligible-area metadata, not a binding eligibility determination.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string",
                "description": "Complete US street address including house number, street name, city, state, and ZIP code. Example: \"123 Main Street, Miami, FL 33139\""
              },
              "property_candidate_key": {
                "type": "string",
                "description": "Smarty property key returned in candidates when address_selection_required is reported."
              }
            },
            "required": [
              "address"
            ]
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "openWorldHint": false,
            "idempotentHint": true
          }
        }
      ]
    },
    {
      "url": "https://app.perilscore.com/chatgpt/mcp",
      "transport": "streamable-http",
      "auth": "none",
      "protocol_version": "2024-11-05",
      "description": "ChatGPT App MCP endpoint (OpenAI Apps SDK). 10,000/day per IP.",
      "tool_count": 1,
      "tools": [
        {
          "name": "get_property_catastrophe_risk_scores",
          "title": "Get Catastrophe Risk Scores",
          "description": "Look up location-based catastrophe risk scores for one US property. Returns per-peril scores on a 0-10 scale for hurricane, wildfire, hail, flood, earthquake, tornado, and crime, with contributing factors, nearest fire-station context, the PerilScore Fire Protection Score, and a link to the interactive report. Crime is reported separately and is not folded into the catastrophe-risk number. All returned data is delivered in one free, non-billable call.\n\nFree ChatGPT app boundary: score exactly one property address per user request. Do not call this tool repeatedly to process multiple addresses, an uploaded file, CSV/XLSX, table, schedule of values, portfolio, book of business, or other bulk request. Ask the user to choose one address instead.\n\nResponse format: the widget renders only headline scores and 1-2 highlights \u2014 the text response must carry the full factor breakdown. Render the `summary` field verbatim as your reply: it is already markdown-formatted, ordered highest-risk first with NA perils last, and ends with the nearest fire station, Protection score, and the deep link. Do not abbreviate, reorder, or add commentary, insurance product recommendations, or affordability claims.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string",
                "description": "Exactly one complete US street address including house number, street name, city, state, and ZIP code. Do not pass an address list, file contents, table, schedule of values, or portfolio.",
                "maxLength": 300
              },
              "property_candidate_key": {
                "type": "string",
                "description": "Smarty property key returned in candidates when address_selection_required is reported."
              }
            },
            "required": [
              "address"
            ]
          },
          "annotations": {
            "readOnlyHint": true,
            "destructiveHint": false,
            "openWorldHint": false,
            "idempotentHint": true
          },
          "outputSchema": {
            "type": "object",
            "properties": {
              "formatted_address": {
                "type": "string"
              },
              "perils": {
                "type": "array"
              },
              "fire_station": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "fire_protection_score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "fire_protection_score_label": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "public_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "deep_link": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "summary": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "_meta": {
            "openai/outputTemplate": "ui://widget/score-card.html",
            "openai/toolInvocation/invoking": "Scoring property risk\u2026",
            "openai/toolInvocation/invoked": "Property risk score ready",
            "securitySchemes": [
              {
                "type": "noauth"
              }
            ],
            "ui": {
              "resourceUri": "ui://widget/score-card.html"
            }
          }
        }
      ]
    }
  ],
  "auth_methods": [
    {
      "type": "none",
      "description": "Public discovery, MCP App resources, and score_address. The free score never consumes a credit."
    },
    {
      "type": "oauth2",
      "description": "OAuth 2.1 + PKCE per RFC 8414/9728/8707 for protected tools. Hosted Claude uses held credentials; Claude Code uses the trusted CIMD client metadata document.",
      "authorization_server_metadata": "https://app.perilscore.com/.well-known/oauth-authorization-server",
      "protected_resource_metadata": "https://app.perilscore.com/.well-known/oauth-protected-resource",
      "hosted_claude_registration": "anthropic-held-credentials",
      "claude_code_client_id": "https://claude.ai/oauth/claude-code-client-metadata",
      "cursor_client_id": "perilscore-cursor-mcp",
      "grok_build_client_id": "perilscore-grok-mcp",
      "scopes": [
        "score:read",
        "score:write",
        "account:read"
      ]
    },
    {
      "type": "bearer-api-key",
      "description": "Authorization: Bearer ps_api_<32 hex>",
      "issue_url": "https://app.perilscore.com/developers/api/"
    }
  ],
  "docs_url": "https://app.perilscore.com/developers/",
  "discovery": {
    "llms_txt": "https://app.perilscore.com/llms.txt",
    "openapi": "https://app.perilscore.com/openapi.json",
    "agent_skill": "https://app.perilscore.com/developers/agent-kit/SKILL.md",
    "agent_kit_zip": "https://app.perilscore.com/developers/agent-kit/build-with-perilscore.zip"
  },
  "support": {
    "email": "info@perilscore.com",
    "connector_review_email": "connectors@perilscore.com",
    "privacy_policy": "https://app.perilscore.com/privacy/",
    "terms_of_service": "https://app.perilscore.com/terms/"
  },
  "category": "financial-services"
}