AIP registry, draft 0.1

This is draft 0.1 of the registry. A later draft can break it until 1.0. The source of truth is registry.ts, and its types are in the schema reference from section R1. When this page and registry.ts differ, registry.ts wins. The tools of each seller are in the specification.

1.Overview

A buying agent calls the registry before it sends anything to a seller. The registry answers three questions, and it needs no customer data to answer them:

• Who sells here? search_distributors returns the sellers that speak AIP in a country, for a line.
• Can this seller sell here? verify_licence checks a seller, or the insurer behind an offer, in the public registers. It works for a seller that the registry does not list.
• Which rules apply here? get_country_rules returns the rules of a country for the buyer skill.

Each seller runs its own MCP server with the tools of the specification. The registry is the global search, and the server of each seller is the one-to-one. The registry does not price, it does not check the underwriting scope of a product, and it does not copy what a server publishes. Those stay on the seller's server.

1.1Roles

• Operator. The organisation that runs the registry. It follows the rules on this page.
• Agent. The AI agent that acts for the customer. It calls the registry, then the seller.
• Seller. A distributor: the company that runs an AIP server and sells the product.
• Provider. The insurer that carries the risk. It can be the seller itself.
• Register. A public list of licensed insurers or intermediaries, kept by a regulator or for one. The registry reads it and never replaces it.

2.Conventions

The conventions of the specification apply. A subdivision is an ISO 3166-2 code, such as US-TX. A domain is a lower-case host name with no scheme and no path, such as pets.example.com.

3.Discovery

The buyer skill gives the address of the registry. The registry declares its extension under capabilities.extensions["org.agenticinsuranceprotocol/registry"] in its MCP server/discover response. The value is a RegistrySettings object: the version, the countries where the registry checks licences, the countries that have rules, every register it reads, and the page where the operator publishes its method.

The registry SHOULD also serve the buyer skill through the MCP Skills extension. An agent whose host loads skills over MCP then gets the whole skill from the registry. get_country_rules serves the same country files to every other agent.

4.Tools

Every registry tool is read-only and needs no session, so the registry never learns who the customer is. The params describe a market or a company, never a person. A registry tool MUST refuse a call with a param that this draft does not define, return invalid_params, and keep nothing of the call.

5.Search

search_distributors takes a country, and optionally a subdivision, a line, an insured family and a minimum conformance level. It returns ListedDistributor objects: the legal and trading names, the domain, the MCP endpoint and the address of poppy.json, the roles, the conformance level, the lines, the countries, the insured families, and the last licence check with its date.

• Each result MUST match every param of the search.
• The registry MUST return every listed seller that matches, across the pages.
• For a country where it lists no seller, the registry returns country_not_covered. An agent then does not read an empty list as "no seller exists".
• The order carries no meaning. The registry MUST NOT rank a seller for a payment or for any commercial link, and it SHOULD shuffle the order for each new search. An agent MUST NOT show the order to the customer as a ranking.

A search result is not a licence check. The agent checks the seller with verify_licence before it sends any of the customer's answers.

6.Licence check

verify_licence answers one question: can this party sell, or carry the risk, for a customer in this country, subdivision and line? It MUST work for a seller that the registry does not list. An agent can find a seller anywhere on the web, and the check matters most then.

6.1What the agent asks

The params are a DistributorCheckParams or a ProviderCheckParams object.

• A seller, with the capacity distributor. The agent gives the domain of the server or the website that will receive the customer's answers. It can add the register entry and the legal name that the seller shows, for example in the legal notice of its website. A register number alone does not prove who runs a website, so a seller check always names the domain.
• A provider, with the capacity provider, for example the insurer in Offer.provider. The agent gives its domain, a register entry, or both. Only a provider role counts.

Both give the customer's country and, when the agent knows it, the line. Where a licence applies per subdivision, the subdivision is REQUIRED. In draft 0.1 that is the United States, where each state grants its own licences.

6.2What the registry reads

The result lists every register entry that the registry read for the party, as LicenceCheck objects, and that includes the entries that are not active. Each entry gives the register and the identifier, the role, the categories, the subdivisions, the countries of an EU passport, the name in the register, the time of the read, how the registry read it, and the public page where anyone can check it.

register_status keeps the status in the words of the register, for example "Authorised" or "Inscrit".

6.3Domains

Any domain can claim any register entry, for example in the get_distributor result of its AIP server. That proves control of the domain and nothing more. DomainLink says how the registry tied the domain to the entries:

6.4Verdict

The registry tests each entry in this order: the country (or an EU passport into it), the subdivision, the line, the role for a provider, then the status. An entry that passes the five tests covers the question.

Each verdict comes with a message in plain words that the agent can pass to the customer. A verdict MUST rest only on reads made at most seven days before it (MAX_READ_AGE_DAYS). The registry SHOULD read the register again for each call when the register has an API or a web page.

6.5What the agent does

The agent MUST check the seller before it sends any of the customer's answers. It MUST check the provider of an offer before it applies or concludes, when the provider is not the seller. It MUST keep each result that it relies on with the record of the sale, and SHOULD give the customer a copy. The result repeats the params of the call, so it is a complete record on its own.

7.Country rules

get_country_rules returns the rules files of the buyer skill for a country. The file of the country comes first. The file of the subdivision and the file of the line follow, when they exist. The agent MUST follow every file of the result. For a country with no file, the registry returns country_not_covered.

Each file is Markdown with a YAML front matter:

---
country: FR
version: 0.1.0
owner: AIP maintainers
status: draft
sources:
  - title: Directive (EU) 2016/97 on insurance distribution
    url: https://eur-lex.europa.eu/eli/dir/2016/97/oj
---

• owner is the AIP maintainers, until a regulator takes the file over.
• status is draft, or endorsed when a regulator endorsed this version. An endorsed file names the regulator in endorsed_by.
• reviewed_at is the date of the last legal review. The key is absent when no review happened.
• A file of a subdivision or of a line adds subdivision or line.
• sources lists the legal texts that the file rests on.

A RulesFile gives the same values, the whole file in content, its SHA-256, its public address, and its URI in the skill that the registry serves over MCP. The text MUST be the same as the file of the same version in the skill, so the hash is the same in both places. When the registry does not answer, the agent uses the copy in its installed skill, and SHOULD tell the customer which version it used.

A regulator that takes over the rules of its country changes one file. Each agent that loads the rules from the registry gets the change on its next call.

8.Listing

A seller asks the operator to be listed. The operator follows these steps:

1. The seller asks to be listed, and gives its domain.
2. The registry reads https://{domain}/.well-known/poppy.json. Its organization.domain MUST be the domain. As PAP requires, the document comes from that host, so it proves that the seller controls the domain.
3. It calls get_distributor on the MCP server that poppy.json names, in the apis entry of type mcp. The domain of the result MUST be the domain.
4. It checks each licence of the result in the public register of its country, as verify_licence does. It also confirms with the holder of each entry that the domain is theirs: the register gives the domain, or the operator asks the holder through contact details that the register or the regulator gives.
5. It checks that the server has every tool of the level it declares, and that the results of the level 1 tools match the schema.
6. It lists the server.

Rules for the operator:

• The registry MUST list a server only when steps 2 to 5 pass. A server that lacks one tool of its level MUST NOT be listed.
• The registry MUST NOT list a server that claims a licence whose status is not_found or name_mismatch. It MUST NOT link a register entry to a second domain unless the holder of the entry confirms the second domain too.
• A listed server appears in a search for a country only while its verdict there is licensed.
• The registry MUST check each listed server again at least every seven days (RECHECK_DAYS), and when the seller or a regulator asks. It SHOULD also check again when anyone reports a problem.
• When a licence stops being active, the registry MUST remove what that licence covered from the listing before it answers another search.
• When poppy.json or the MCP server goes away, or the server fails step 5, the registry MUST remove the listing.
• The registry keeps the fields of ListedDistributor and the licences. It MUST NOT copy the products, the underwriting scopes, the prices or the documents of a server.

9.Data sources

The registry reads public registers. It MUST read a register only through an access that the terms of the register allow, and under an agreement when the terms ask for one. This table gives what we found on the official pages on 24 October 2026. "Not verified" marks each fact that no official page confirmed.

9.1At launch

With no agreement, a first registry can check:

• the insurers of France, from REGAFI, after the ACPR confirms in writing that the registry may reuse the data;
• the insurers of the EEA, including those that sell in France on a passport, from the EIOPA register;
• the agents and agencies of Texas, from the open data of the Texas Department of Insurance;
• the legal identity of a company in any country, from GLEIF. The LEI and the SIREN join GLEIF to REGAFI, EIOPA and ORIAS.

The intermediaries of the three countries need an agreement: NIPR for the United States, the FCA for the United Kingdom, and ORIAS for France. The insurers of the United States need one with the NAIC. NIPR also asks for a "permissible purpose" under the Fair Credit Reporting Act, and we have not verified that a registry qualifies. Until these agreements exist, verify_licence returns unknown with the reason country_not_covered for what the registry cannot read. The FCA's "re-sale use" licence names the use of the registry: to help users find out if a firm is regulated.

9.2Domains in the registers

ORIAS, the EIOPA register and the NAIC show the website of an entry. The FCA Register can show one, and we have not verified that its API returns it. NIPR and the Texas data show none. When a register gives the website, the registry can tie a domain to the entry with the link register. The firm declares its website to the register itself, so another firm cannot add its own domain to the entry. In the other cases, the operator confirms the domain with the holder of the entry.

9.3Status labels

The registry maps the labels of each register to a LicenceStatus, and keeps the label in register_status:

10.Trust and privacy

• Every result says where its data comes from and when the registry read it: the register, the access (API, file or web page), the date of the data in the source, the time of the read, and the public page of the entry.
• The registry never receives customer data. Its tools need no session, and their params describe a market or a company. Check RG8 tests the params of each tool against a closed list of fields.
• The registry SHOULD keep each verify_licence result under its check_id for at least five years, so that it can confirm later what it said.
• Draft 0.1 does not sign results, so an agent cannot yet prove alone what the registry said. See the open points.

11.Errors

A registry tool returns an error in an MCP tool result with isError: true, as a RegistryError in structuredContent.error.

12.Worked example

These calls go with the pet insurance flow. The rules, the search and the seller checks come before it, and the insurer check comes before the application. All companies are fictional.

Load the rules of the country

get_country_rules · examples/registry-01-get_country_rules.params.json · examples/registry-02-get_country_rules.result.json

Camille lives in France and wants to insure her cat. The agent first loads the rules of France. The file is the one of the buyer skill, with its version, its owner, its status and its hash. This example shows the start of a draft file.

{
  "country": "FR",
  "line": "pet"
}

{
  "files": [
    {
      "country": "FR",
      "version": "0.1.0",
      "owner": "AIP maintainers",
      "status": "draft",
      "language": "en",
      "content": "---\ncountry: FR\nversion: 0.1.0\nowner: AIP maintainers\nstatus: draft\nsources:\n  - title: Directive (EU) 2016/97 on insurance distribution\n    url: https://eur-lex.europa.eu/eli/dir/2016/97/oj\n  - title: ORIAS, register of insurance intermediaries\n    url: https://www.orias.fr/\n---\n\n# France\n\nDraft. No lawyer and no regulator has reviewed this file.\n\n## Who may sell\n\n1. Check the seller with `verify_licence`, with the country FR, before you send any answer of the customer.\n2. Check the insurer behind each offer in the same way.\n",
      "sha256": "77d335989962efdb591010bd8ebd744d013aa9d70df071204374d47cffc4c663",
      "url": "https://registry.example.com/rules/fr/0.1.0.md",
      "skill_uri": "skill://buy-insurance/references/countries/fr.md"
    }
  ]
}

Find the sellers

search_distributors · examples/registry-03-search_distributors.params.json · examples/registry-04-search_distributors.result.json

The agent asks the registry for the sellers of pet insurance in France that can at least quote. The registry returns Example Pets, with the register entry that its listing rests on.

{
  "country": "FR",
  "line": "pet",
  "min_conformance_level": 2
}

{
  "distributors": [
    {
      "legal_name": "Example Pets SAS",
      "trading_name": "Example Pets",
      "domain": "pets.example.com",
      "mcp_url": "https://pets.example.com/mcp",
      "poppy_url": "https://pets.example.com/.well-known/poppy.json",
      "roles": [
        "broker"
      ],
      "conformance_level": 3,
      "lines": [
        "pet"
      ],
      "countries": [
        "FR"
      ],
      "insured_families": [
        "pet"
      ],
      "licence_check": {
        "entries": [
          {
            "country": "FR",
            "identifier_type": "orias_number",
            "identifier": "00000000"
          }
        ],
        "checked_at": "2026-10-18T03:00:00+02:00"
      },
      "listed_since": "2026-10-01"
    }
  ]
}

Check a listed seller

verify_licence · examples/registry-05-verify_licence.params.licensed.json · examples/registry-06-verify_licence.result.licensed.json

Before it sends any answer, the agent checks the domain that will receive them. The registry reads the ORIAS entry again, and the entry gives the website of Example Pets, so the link is register. The verdict is licensed. The agent keeps this result with the record of the sale.

{
  "capacity": "distributor",
  "subject": {
    "domain": "pets.example.com"
  },
  "country": "FR",
  "line": "pet"
}

{
  "check_id": "chk-4d1e",
  "params": {
    "capacity": "distributor",
    "subject": {
      "domain": "pets.example.com"
    },
    "country": "FR",
    "line": "pet"
  },
  "subject": {
    "legal_name": "Example Pets SAS",
    "domain": "pets.example.com",
    "domain_link": "register",
    "listed": true,
    "mcp_url": "https://pets.example.com/mcp"
  },
  "licences": [
    {
      "country": "FR",
      "regulator": "ACPR",
      "register": "ORIAS",
      "identifier_type": "orias_number",
      "identifier": "00000000",
      "role": "broker",
      "status": "active",
      "register_status": "Inscrit",
      "categories": [
        "COA"
      ],
      "name_in_register": "EXAMPLE PETS SAS",
      "access": "api",
      "checked_at": "2026-10-20T09:58:00+02:00",
      "source_url": "https://www.orias.fr/"
    }
  ],
  "outcome": {
    "verdict": "licensed",
    "message": "Example Pets SAS is in the ORIAS register as an insurance broker (COA), and the entry is active."
  },
  "checked_at": "2026-10-20T09:58:01+02:00"
}

Check a seller found on the web

verify_licence · examples/registry-07-verify_licence.params.no_licence.json · examples/registry-08-verify_licence.result.no_licence.json

Another site sells pet cover and gives an ORIAS number in its legal notice. ORIAS has no such entry. The verdict is not_licensed, so the agent sends nothing to that site and tells Camille why.

{
  "capacity": "distributor",
  "subject": {
    "domain": "petcover.example.com",
    "identifier": {
      "country": "FR",
      "identifier_type": "orias_number",
      "identifier": "00000001"
    },
    "legal_name": "Pet Cover Online SARL"
  },
  "country": "FR",
  "line": "pet"
}

{
  "check_id": "chk-4d2a",
  "params": {
    "capacity": "distributor",
    "subject": {
      "domain": "petcover.example.com",
      "identifier": {
        "country": "FR",
        "identifier_type": "orias_number",
        "identifier": "00000001"
      },
      "legal_name": "Pet Cover Online SARL"
    },
    "country": "FR",
    "line": "pet"
  },
  "subject": {
    "domain": "petcover.example.com",
    "domain_link": "not_linked",
    "listed": false
  },
  "licences": [
    {
      "country": "FR",
      "regulator": "ACPR",
      "register": "ORIAS",
      "identifier_type": "orias_number",
      "identifier": "00000001",
      "status": "not_found",
      "access": "api",
      "checked_at": "2026-10-20T09:59:00+02:00",
      "source_url": "https://www.orias.fr/"
    }
  ],
  "outcome": {
    "verdict": "not_licensed",
    "reason": "no_entry",
    "message": "ORIAS has no entry with the number 00000001, and no entry in the name of Pet Cover Online SARL. This seller is not registered to sell insurance in France."
  },
  "checked_at": "2026-10-20T09:59:01+02:00"
}

Check a seller whose licence lapsed

verify_licence · examples/registry-09-verify_licence.params.lapsed.json · examples/registry-10-verify_licence.result.lapsed.json

In another sale, in the United States, a licence applies per state, so the agent gives the state. The operator confirmed the agency's domain when it listed it. The Texas licence lapsed, and the Oklahoma licence does not cover a customer in Texas. The verdict is not_licensed, and the reason comes from the Texas entry.

{
  "capacity": "distributor",
  "subject": {
    "domain": "agency.example.com"
  },
  "country": "US",
  "subdivision": "US-TX",
  "line": "pet"
}

{
  "check_id": "chk-7b90",
  "params": {
    "capacity": "distributor",
    "subject": {
      "domain": "agency.example.com"
    },
    "country": "US",
    "subdivision": "US-TX",
    "line": "pet"
  },
  "subject": {
    "legal_name": "Example Pet Agency LLC",
    "domain": "agency.example.com",
    "domain_link": "confirmed",
    "listed": false
  },
  "licences": [
    {
      "country": "US",
      "register": "NIPR Producer Database",
      "identifier_type": "npn",
      "identifier": "00000000",
      "role": "agent",
      "categories": [
        "Property",
        "Casualty"
      ],
      "lines": [
        "home",
        "renters",
        "motor",
        "pet"
      ],
      "name_in_register": "EXAMPLE PET AGENCY LLC",
      "access": "api",
      "checked_at": "2026-10-21T15:40:00-05:00",
      "source_url": "https://nipr.com/",
      "regulator": "Texas Department of Insurance",
      "subdivisions": [
        "US-TX"
      ],
      "status": "lapsed",
      "register_status": "Inactive",
      "valid_until": "2026-08-31"
    },
    {
      "country": "US",
      "register": "NIPR Producer Database",
      "identifier_type": "npn",
      "identifier": "00000000",
      "role": "agent",
      "categories": [
        "Property",
        "Casualty"
      ],
      "lines": [
        "home",
        "renters",
        "motor",
        "pet"
      ],
      "name_in_register": "EXAMPLE PET AGENCY LLC",
      "access": "api",
      "checked_at": "2026-10-21T15:40:00-05:00",
      "source_url": "https://nipr.com/",
      "regulator": "Oklahoma Insurance Department",
      "subdivisions": [
        "US-OK"
      ],
      "status": "active",
      "register_status": "Active",
      "valid_until": "2027-05-31"
    }
  ],
  "outcome": {
    "verdict": "not_licensed",
    "reason": "licence_not_active",
    "message": "Example Pet Agency LLC holds no active licence in Texas. Its Texas licence ended on 31 August 2026. Its licence in Oklahoma is active, but it does not cover a customer in Texas."
  },
  "checked_at": "2026-10-21T15:40:01-05:00"
}

Check the insurer

verify_licence · examples/registry-11-verify_licence.params.provider.json · examples/registry-12-verify_licence.result.provider.json

Back in France, before it applies for the offer, the agent checks Example Mutual, the insurer that carries the risk. A provider check can use the register entry from Offer.provider alone. The ACPR register shows an active authorisation, so the verdict is licensed.

{
  "capacity": "provider",
  "subject": {
    "identifier": {
      "country": "FR",
      "identifier_type": "lei",
      "identifier": "EXAMPLEMUTUAL0000042"
    }
  },
  "country": "FR",
  "line": "pet"
}

{
  "check_id": "chk-4d3c",
  "params": {
    "capacity": "provider",
    "subject": {
      "identifier": {
        "country": "FR",
        "identifier_type": "lei",
        "identifier": "EXAMPLEMUTUAL0000042"
      }
    },
    "country": "FR",
    "line": "pet"
  },
  "subject": {
    "legal_name": "Example Mutual Assurances SA",
    "lei": "EXAMPLEMUTUAL0000042",
    "listed": false
  },
  "licences": [
    {
      "country": "FR",
      "regulator": "ACPR",
      "register": "REGAFI",
      "identifier_type": "lei",
      "identifier": "EXAMPLEMUTUAL0000042",
      "role": "insurer",
      "status": "active",
      "register_status": "Actif",
      "categories": [
        "Non-vie"
      ],
      "name_in_register": "EXAMPLE MUTUAL ASSURANCES SA",
      "access": "api",
      "source_date": "2026-10-19",
      "checked_at": "2026-10-20T10:04:20+02:00",
      "source_url": "https://www.regafi.fr/"
    }
  ],
  "outcome": {
    "verdict": "licensed",
    "message": "Example Mutual Assurances SA is in the ACPR register of insurers, and its authorisation is active."
  },
  "checked_at": "2026-10-20T10:04:21+02:00"
}

13.Checks

The repository checks the examples against schema.json, and against the registry rules that a JSON Schema cannot express:

• RG1 a search returns only listed servers that match every param.
• RG2 the verdict of a licence check follows from the entries it read and from the domain link.
• RG3 every entry was read at most seven days before the verdict.
• RG4 a licence check repeats the params of the call.
• RG5 a check in a country where licences apply per subdivision gives the subdivision.
• RG6 the hash and the front matter of a rules file match the file.
• RG7 the rules start with the file of the country.
• RG8 the registry tools need no session, and their params hold no customer data.

The listing steps, the order of the search results and the schedule of the checks are rules about how the operator works. A test of a live registry can check them. The examples cannot.

14.Open points

1. Signed results. A signature on each verify_licence result would let an agent prove later what the registry said, with no call to the registry. Draft 0.1 leaves signatures out. A later draft can add them, for example with a key that RegistrySettings publishes.
2. Reading a past check. The registry keeps each result under its check_id, but no tool reads it back yet.
3. Confirming a domain. The operator confirms the link between a domain and a register entry with its own method. A later draft can define one channel for it, for example a code that the register or the regulator sends to the holder.
4. Names and categories. How the registry compares a name with the name in a register, and how it maps the categories of a register to lines, is the operator's method for now. The operator publishes it at policy_url.
5. US states. The rules files of the US states come later. The US file covers the common points and says that the rules differ by state.
6. Data agreements. The intermediaries of the United States, the United Kingdom and France need an agreement with NIPR, the FCA and ORIAS. The insurers of the United States need one with the NAIC. See At launch.