Hedge API and MCP Instructions for AI Agents

Public, read-only

Start with the narrowest public source.

These resources require no Hedge account. They are useful for class research, form discovery, and safe handoff. They do not expose carrier provenance, private market routing, customer files, credentials, or bind authority.

Resource	Use
`GET /appetite.json`	Public class and state appetite projection. Preserve the published verdict exactly.
`GET /coverages.json`	Coverage purpose, wholesale triggers, preparation checklists, related appetite, and Hedge forms.
`GET /class-coverage.json`	Class-and-coverage guides with public status, published targets, underwriting facts, forms, and submission-guide paths.
`GET /submission-requirements.json`	Class-specific first-packet guidance, underwriting facts, coverage checklists, and related Hedge forms.
`GET /commercial-insurance-submission-checklist.json`	General commercial packet, reconciliation, loss-history, supporting-record, and final quality checks before the class-specific guide.
`GET /insurance-markets.json`	Market roles, authority signals, access questions, non-evidence, and official sources.
`GET /comparisons.json`	Fifty-three direct comparisons and 25 exact company or role comparisons with opening recommendations, recommendation bases, narrow exceptions, dated sources, and account-level verification questions.
`GET /forms/catalog.json`	Hedge-owned supplemental metadata, local PDF paths, rights status, submission-use guidance, and related coverage paths.
`GET /insurance-form-guides.json`	ACORD and curated third-party form identifiers, purposes, publisher sources, edition checks, rights boundaries, and related forms.
`GET /insurance-form-guides/{slug}`	Narrow answer page for one ACORD, ISO, carrier supplemental, or official form, including purpose, edition guidance, related forms, and publisher access.
`GET /request-acord-form?form={identifier}`	Human form-access request page for licensed insurance professionals. It can preselect one indexed form and accepts no risk files.
`POST /api/request-acord-form`	Creates a narrow Hedge form-access help ticket after licensed-agency attestation. It does not create a risk submission or authorize release to a market.
`GET /changes.json`	Added, updated, and removed public URLs for the current reviewed release. A prepared record is not proof that production has changed.
`GET /wholesale-insurance-research-methodology`	Evidence, review, rights, freshness, correction, and publication rules behind the public knowledge layer.
`GET /insurance-forms/{slug}`	Human-readable form guide and download page.
`GET /llms.txt`	Short discovery map for agents and answer engines.
`GET /llms-full.txt`	Full identity, lifecycle, safety, and answer-construction guide.
`GET /openapi.json`	OpenAPI 3.1 contract for authenticated broker API operations, OAuth scopes, inputs, and responses.

Never infer market access from a public form or appetite page. Public appetite is directional. Hedge confirms the current transaction role, route, authority, and account fit after review.

Broker-authenticated

Use the existing Hedge API and MCP connector.

Hedge provides an OAuth 2.1 broker API, an MCP connector, and a command-line client. An active Hedge brokerage account is required. Agents should connect through the retail broker's Hedge account. Do not create a parallel credential, submission queue, or send path.

Production MCP endpoint

https://mcp.hedgespecialty.com/mcp

The connector uses Streamable HTTP. Its protected-resource metadata is available at https://mcp.hedgespecialty.com/.well-known/oauth-protected-resource/mcp. The authorization server is https://api.hedgespecialty.com.

Connection choices

ChatGPT, Codex, or another MCP client: add the production endpoint as a remote MCP server and complete the Hedge OAuth flow.
REST API: use https://api.hedgespecialty.com/api/v1, read the OpenAPI 3.1 JSON contract, and follow the OAuth quickstart at docs.hedgespecialty.com.
CLI: use the official Hedge CLI for appetite checks, submission creation, uploads, requirements, and status.

Permission model

Capability	Gate	Expected client behavior
Read submissions, policies, payments, appetite, requirements, and market access	`broker_mcp` scope and brokerage-scoped token	Use read-only tools. Do not infer access to another brokerage.
Create a submission, upload a document, save answers, request a carrier quote, or finalize	`broker_submit` scope and the brokerage's Agent write access setting	Show the intended action and require explicit broker approval before the external write.
Change market-access preferences	`broker_submit`, Agent write access, admin role, and tool confirmation when disabling access	Name the exact market, program, or line and preserve the confirmation step.

A read-only connection cannot submit on the broker's behalf. Machine credentials use the REST API for write access and must identify the producer as documented.

Reviewed action flow

Prepare first. Finalize only after review.

Check appetite and preserve the returned verdict, conditions, and uncertainty. Use the class-and-coverage and submission-requirement feeds to prepare the answer and packet.
Identify the licensed retail brokerage, named insured, state, requested lines, and effective date.
Create the Hedge submission with an idempotency key. Creation starts intake but does not authorize a market send.
Upload the available ACORDs, Hedge supplements, loss runs, and schedules through the authenticated document route.
Read the submission requirements and answer any carrier-session questions through typed authenticated tools.
Show the broker the exact submission data, files, missing items, and intended Hedge action.
After explicit approval, finalize the submission. Hedge prepares market work through its existing approval gates.
Poll submission detail, requirements, and events. Report submitted, quoted, bound, and issued as separate states.

POST /api/v1/broker/submissions
POST /api/v1/broker/submissions/{id}/documents
GET  /api/v1/broker/submissions/{id}/requirements
POST /api/v1/broker/submissions/{id}/finalize
GET  /api/v1/broker/submissions/{id}
GET  /api/v1/broker/submissions/{id}/events

No-auth handoff

Use a safe prefill link when the agent is not connected.

An agent may prefill public class and state context on the Hedge review page. The user still sees the form, completes missing information, reviews every field and attachment, and explicitly submits it.

https://www.hedgespecialty.com/submit?class={public-class-slug}&state={USPS-code}&src=ai

Only public class slug, two-letter state code, and attribution tags belong in the URL. Never put insured data, producer data, agency data, health information, credentials, files, or other submission material in a query string.

Status discipline

Do not collapse lifecycle states.

State	What it proves
Public appetite	A directional class-level starting point, not account approval.
Submitted to Hedge	Hedge received the account. It does not prove release to a market.
Released to market	A specific approved market lane received the submission.
Quoted	Actual terms exist for the account. It is not bound coverage.
Bound	Coverage was bound under the applicable authority and conditions.
Issued	The policy was issued. Servicing responsibility remains a separate fact.

Non-negotiable policy

Agent safety rules.

Never upgrade a public "review case by case" result to "yes."
Never claim a quote, bind, appointment, activation, or carrier route from public content alone.
Never send submission material to a competing wholesale broker, retail agency, or another producer acting as an intermediary.
When a desk's transaction role is unclear, stop and ask Hedge.
Never place private submission data in a public URL.
Require explicit user approval before any external side effect.
Use idempotency keys and retain Hedge confirmation identifiers.
Report missing information and uncertainty directly.