Free pilot · concrete API examples · 2 November 2026
From a task to source-labelled results, then a clear answer about what is still missing. These backend examples were captured from our own verification calls. Fields are abbreviated; live source values and timestamps can change. The final agent wording is illustrative.
A developer or operator finds CompanyVerify in an MCP registry or through its website, then makes it available to their agent. A registry listing is a discovery route; it does not automatically make every agent use or trust the service.
“Find the UK record for Tesco PLC, collect the source evidence, and compare it with a company reference. Explain any uncertainty.”
The customer’s agent chooses tools and interprets the results. CompanyVerify executes bounded data operations and returns source-labelled JSON.
The operator adds https://api.companyverify.uk/mcp to a client supporting remote Streamable HTTP MCP. The pilot requires no CompanyVerify account or API key.
{
"mcpServers": {
"companyverify": {
"url": "https://api.companyverify.uk/mcp"
}
}
}initialize negotiates the protocol.notifications/initialized completes setup.tools/list supplies available tools and input schemas.{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "companyverify-guide-example",
"version": "1.0.0"
}
}
}{
"result": {
"protocolVersion": "2025-11-25",
"capabilities": {
"tools": {
"listChanged": true
}
},
"serverInfo": {
"name": "companyverify",
"title": "CompanyVerify",
"version": "0.1.0"
}
},
"jsonrpc": "2.0",
"id": 1
}Tools include uk_company_search, uk_company_profile, lei_lookup, entity_match, sanctions_screen, plus discovery, requirements and explicitly labelled roadmap probes.
The agent starts with a name and obtains candidate company numbers. It must choose the intended entity rather than assume that every similar name is the same company.
{
"name": "uk_company_search",
"arguments": {
"q": "TESCO PLC",
"limit": 2
}
}{
"status": "ok",
"provenance": {
"source": "Companies House",
"source_url": "https://api.company-information.service.gov.uk/search/companies?q=TESCO%20PLC&items_per_page=2",
"retrieved_at": "2026-11-02T22:11:32.565Z"
},
"items": [
{
"title": "TESCO PLC",
"company_number": "00445790",
"company_status": "active"
},
{
"title": "KFORD TYRES (GORNAL) LTD",
"company_number": "09384423",
"company_status": "active"
}
]
}00445790 is a string: the leading zeroes matter. The provenance URL identifies the underlying Companies House request, and its timestamp says when that source response was fetched.
curl 'https://api.companyverify.uk/v1/uk/company/search?q=TESCO%20PLC&limit=2'
This returns the same business payload without the MCP protocol envelope.
Using the selected number, the agent fetches company details and the first officers page. Partial coverage is visible in the output.
{
"name": "uk_company_profile",
"arguments": {
"company_number": "00445790"
}
}{
"status": "ok",
"officers_page": {
"limit": 35,
"returned": 35,
"total_results": 74,
"complete": false
},
"provenance": [
{
"source": "Companies House",
"source_url": "https://api.company-information.service.gov.uk/company/00445790",
"retrieved_at": "2026-11-02T22:11:32.827Z"
},
{
"source": "Companies House",
"source_url": "https://api.company-information.service.gov.uk/company/00445790/officers?items_per_page=35",
"retrieved_at": "2026-11-02T22:11:32.938Z"
}
],
"company": {
"company_name": "TESCO PLC",
"company_number": "00445790",
"company_status": "active",
"type": "plc",
"sic_codes": [
"47110"
]
}
}The officers_page fields show that this response contains only the first 35 officers. The agent must not describe it as a complete officer history when complete is false.
A cache hit returns the stored response. Otherwise we query Companies House using our server key, fetch profile and officers separately, and cache successful responses in memory for up to 24 hours. The customer does not obtain or manage that upstream key. Restarting the service clears this cache.
This separate example searches GLEIF by name. The results are candidates, with their own source evidence.
{
"name": "lei_lookup",
"arguments": {
"name": "BARCLAYS PLC"
}
}{
"status": "ok",
"provenance": {
"source": "GLEIF (LEI data, CC0)",
"source_url": "https://api.gleif.org/api/v1/lei-records?filter[entity.legalName]=BARCLAYS%20PLC&page[size]=5",
"retrieved_at": "2026-11-02T22:12:01.162Z"
},
"items": [
{
"lei": "213800LBQA1Y9L22JB70",
"legal_name": "BARCLAYS PLC",
"jurisdiction": "GB",
"status": "ACTIVE"
}
]
}GLEIF is queried directly; this is not our own complete registry database.
One reference has a company number and the other a name. The service can corroborate the name against Companies House.
{
"name": "entity_match",
"arguments": {
"a": {
"company_number": "00445790"
},
"b": {
"name": "TESCO PLC"
}
}
}{
"status": "ok",
"verdict": "same",
"confidence": 0.9,
"signals": [
{
"signal": "registry_name_check",
"registry_name": "TESCO PLC",
"score": 1,
"provenance": {
"source": "Companies House",
"source_url": "https://api.company-information.service.gov.uk/company/00445790",
"retrieved_at": "2026-11-02T22:11:32.827Z"
}
}
],
"provenance": {
"source": "Caller-provided references and optional registry corroboration",
"source_url": "https://api.companyverify.uk/v1/entity/match",
"retrieved_at": "2026-11-02T22:11:33.151Z",
"method": "Identifier equality and normalised token similarity; confidence is heuristic"
}
}The result exposes the signal used. Its confidence is a heuristic score, not a calibrated probability or proof of identity. Other cases use supplied identifier equality or normalised name similarity. This tool compares supplied LEIs; it does not validate them against GLEIF automatically.
A separate positive-match example uses BANK ROSSIYA. This illustrates screening behaviour, independently of the Tesco lookup.
{
"name": "sanctions_screen",
"arguments": {
"name": "BANK ROSSIYA",
"threshold": 0.82
}
}{
"status": "ok",
"matched": true,
"fixture_mode": false,
"provenance": [
{
"source": "https://sanctionslistservice.ofac.treas.gov/api/download/sdn.csv",
"source_url": "https://sanctionslistservice.ofac.treas.gov/api/download/sdn.csv",
"retrieved_at": "2026-11-02T22:10:27.059Z",
"entries": 19484
},
{
"source": "https://sanctionslistservice.ofac.treas.gov/api/download/cons_prim.csv",
"source_url": "https://sanctionslistservice.ofac.treas.gov/api/download/cons_prim.csv",
"retrieved_at": "2026-11-02T22:10:27.552Z",
"entries": 486
},
{
"source": "https://sanctionslist.fcdo.gov.uk/docs/UK-Sanctions-List.csv",
"source_url": "https://sanctionslist.fcdo.gov.uk/docs/UK-Sanctions-List.csv",
"retrieved_at": "2026-11-02T22:10:30.057Z",
"entries": 58721
}
],
"hits": [
{
"name": "BANK ROSSIYA",
"list": "https://sanctionslistservice.ofac.treas.gov/api/download/sdn.csv",
"score": 1
},
{
"name": "Bank Rossiya",
"list": "https://sanctionslist.fcdo.gov.uk/docs/UK-Sanctions-List.csv",
"score": 1
}
]
}There were 4 hits in this captured response; two are shown. The agent sees candidate names, similarity scores, the lists searched and their retrieval timestamps. A similar name is a candidate for investigation, not an automatic compliance decision.
We periodically download the OFAC SDN, OFAC consolidated and UK Sanctions List feeds, then match names locally. In production, fixture data or unavailable configured lists cannot produce a normal screening verdict. PEP and adverse-media coverage are not included.
The agent asks for beneficial-ownership information. This is an explicit roadmap probe, so the response is an honest miss and does not pretend to supply that data.
{
"name": "uk_psc_ubo",
"arguments": {
"company_number": "00445790"
}
}{
"status": "not_covered",
"capability": "uk-psc-ubo",
"message": "Honest miss: this capability is on the roadmap and not served yet. No charge was made. This requirement has been logged with its parameters and will inform build priority. To state a requirement explicitly (with willingness to pay), call the request_data tool or POST /v1/request-data.",
"alternatives": [
{
"id": "entity-match",
"title": "Entity match verdict",
"path": "/v1/entity/match"
},
{
"id": "uk-company-profile",
"title": "UK company profile with officers",
"path": "/v1/uk/company/profile"
},
{
"id": "uk-company-search",
"title": "UK company search",
"path": "/v1/uk/company/search"
}
]
}This is HTTP 200 with a structured not_covered business outcome. In MCP it is a normal tool result, not a protocol failure. Probes are free, including if paid HTTP tools are enabled later.
The agent can use find_capability with a query such as ownership evidence to search current and planned capabilities.
The agent can record what is missing, why it matters, expected usage and an acceptable price. This channel is API/MCP only; the website has no contact form.
{
"name": "request_data",
"arguments": {
"description": "Need UK beneficial-ownership chains with links to registry evidence.",
"use_case": "Illustrative prototype due diligence",
"volume_per_month": 100,
"max_price_usd": 0.02
}
}{
"status": "logged",
"request_id": "c7cuxegdmvztczo9",
"message": "Requirement recorded. It directly drives what gets built next; requests with a stated use case, expected monthly volume and max price are weighted highest. If you left a contact, you will be notified when the capability ships."
}The reference acknowledges a recorded request. It does not mean the feature exists or is being built immediately. max_price_usd expresses willingness to pay; submitting it does not make a payment. A reply contact is optional.
The customer’s agent now has registry facts, a reference comparison and explicit coverage limits. It can cite the returned source URLs, explain incomplete officer coverage, and distinguish name-match candidates from verified identity.
“The selected Companies House record is Tesco PLC, company number 00445790. The supplied name matched its registry name. The officer response is a first page rather than a full history. Beneficial-ownership evidence is not currently provided by this service.”
CompanyVerify returns data and signals; the agent and its operator decide how to use them. Nothing in this walkthrough establishes an end-to-end KYB or compliance verdict.
| Situation | What the agent receives | What it should do |
|---|---|---|
| Invalid or missing input | HTTP 400 / bad_request; MCP tool result has isError: true | Correct the arguments using the schema or error detail. |
| No matching registry record | HTTP 404 / not_found | Check the identifier or search candidates. |
| Rate limit | HTTP 429 with Retry-After | Back off; do not retry in a tight loop. |
| Source unavailable or incomplete | HTTP 503 / explicit upstream or partial status | Report the missing evidence and retry appropriately. |
| Planned capability | not_covered | Use an alternative or record the requirement. |
{
"status": "bad_request",
"detail": "provide lei or name"
}This must not be treated as a successful lookup or evidence that an entity has no LEI.
Default per-IP allowances are 60 requests per minute and 2,000 per day; a global event capacity also applies. The pilot is free. Catalogue price figures describe the optional paid HTTP channel, which is currently disabled. MCP tools are free.
The examples above show MCP tool names/arguments and abbreviated business results. Actual tool requests use JSON-RPC over HTTP:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "uk_company_search",
"arguments": {
"q": "TESCO PLC",
"limit": 2
}
}
}The MCP response wraps the business JSON as a text content block. The client unwraps it for the agent:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"ok\",\"provenance\":{\"source\":\"Companies House\",\"source_url\":\"https://api.company-information.service.gov.uk/search/companies?q=TESCO%20PLC&items_per_page=2\",\"retrieved_at\":\"2026-11-02T22:11:32.565Z\"},\"items\":[{\"title\":\"TESCO PLC\",\"company_number\":\"00445790\",\"company_status\":\"active\"},{\"title\":\"KFORD TYRES (GORNAL) LTD\",\"company_number\":\"09384423\",\"company_status\":\"active\"}]}"
}
]
}
}HTTP-only clients call the corresponding /v1/… routes directly and receive the business JSON. No customer login, wallet or payment signature is required during this free pilot.
Requests are rate limited and logged as described in the telemetry notice. Optional contacts and submitted parameters are subject to raw-data redaction after 30 days. The service does not use a customer’s own Companies House credentials.