Hedge API and MCP Instructions for AI Agents

Public, read-only

Start with the narrowest public source.

Public resources 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 answers 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 /insurance-markets.json`	Market roles, authority signals, access questions, non-evidence, and official sources.
`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`	Common commercial form numbers, purposes, source references, review checks, and related Hedge-owned forms.
`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.

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. 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

Claude: add a custom connector with the production MCP endpoint, then sign in to Hedge.
ChatGPT, Codex, or another MCP client: add the same endpoint as a remote MCP server and complete the Hedge OAuth flow.
Claude Code: run claude mcp add --transport http --client-id hedge-broker-mcp hedge https://mcp.hedgespecialty.com/mcp, then use /mcp to sign in.
REST API: use https://api.hedgespecialty.com/api/v1 and follow the OAuth quickstart and public OpenAPI 3.1 contract 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.

Wholesale knowledge

Company

Research openly. Act with approval.