DEV Community: fargerod-dotcom

Check a UK supplier at Companies House from Claude Code — and the same tool works for Norway

fargerod-dotcom — Fri, 04 Sep 2026 18:27:28 +0000

A new supplier sends an invoice with a company registration number on it. Is the company real, still trading, and up to date on its filings? registry-mcp answers from Companies House by company number — and from Brønnøysundregistrene / Enhetsregisteret (brreg) by organisasjonsnummer (orgnr, org.nr), with the same tool and the same JSON.

claude mcp add registry-mcp --transport http https://api.foretak.dev/mcp
# or locally, over stdio: uvx registry-mcp

The prompt

Invoice from Tesco PLC, company number 00445790. Is it active, and is it up to date at Companies House?

The call

lookup_company(id="00445790", country="GB")

{
  "id": "00445790",
  "name": "TESCO PLC",
  "legal_form_code": "plc",
  "legal_form": "Public limited company",
  "status": "active",
  "is_active": true,
  "registered_at": "1947-11-27",
  "registers": {"charges": false, "insolvency": false},
  "vat_registered": null,
  "employees": null,
  "source": "Companies House (UK)",
  "source_url": "https://find-and-update.company-information.service.gov.uk/company/00445790",
  "license": "Crown copyright — Companies House public register, free to re-use"
}

Read the nulls literally. Companies House publishes no VAT status and no employee count, for any company — null means "this register does not say", never "no". Norway publishes both:

{
  "country": "NO",
  "name": "EQUINOR ASA",
  "vat_registered": true,
  "vat_number": "NO923609016MVA",
  "employees": 21239,
  "source": "Enhetsregisteret (Brønnøysundregistrene)"
}

One shape, two registers, honest about which publishes what.

The half that's actually useful

Companies House publishes each company's own filing due dates, so company_deadlines quotes them rather than guessing. Deloitte's LLP, on 4 September 2026:

{
  "company_name": "DELOITTE LLP",
  "today": "2026-09-04",
  "deadlines": [
    {"kind": "confirmation_statement", "local_name": "Confirmation statement (CS01)",
     "due_date": "2026-08-14", "days_until": -21,
     "applies_because": "Companies House publishes this date for the company itself; it is the register's own figure, not a calculation."},
    {"kind": "annual_accounts", "local_name": "Annual accounts",
     "due_date": "2027-02-28", "period_end": "2026-05-31", "days_until": 177}
  ]
}

days_until: -21 is not a stale response. Companies House leaves an overdue date in the past instead of rolling it forward, so the negative number is the answer: that confirmation statement is three weeks late. UK deadlines never move off a weekend or bank holiday either — a Sunday deadline is a Sunday deadline in law. applies_because says whether a date is quoted or computed; quote it.

Two things that will trip your agent

The country code is GB, not UK.

{
  "error": {
    "code": "unsupported_country",
    "message": "No registry module is available for country 'UK'.",
    "hint": "Call list_countries (MCP) or GET /v1/countries (REST) for the current list. Supported right now: GB, NO."
  }
}

Every error names its own fix in hint.

A UK company number has no check digit. So validate_company_id is a normaliser first:

{
  "input": "445790",
  "valid": true,
  "normalized": "00445790",
  "formatted": null
}

Short numbers are zero-padded, prefixes upper-cased (oc303675 → OC303675). But valid: true means the shape is right, nothing more: a mistyped UK number is well-formed and comes back 404 not_found. Norway's MOD11 catches a transposed digit; the UK has nothing to catch it with. And sole traders and ordinary partnerships are not on the register at all, so a missing UK business is often a real one.

Companies House data: Crown copyright, free to re-use. Norwegian data: Enhetsregisteret, NLOD 2.0. Same JSON over MCP and REST.
Repo: https://github.com/foretak/registry-mcp

Add your country's company registry to registry-mcp in an afternoon

fargerod-dotcom — Fri, 04 Sep 2026 18:27:18 +0000

registry-mcp is a company registry MCP server. Today it answers for one country — Norway's Brønnøysundregistrene / Enhetsregisteret (brreg), by organisasjonsnummer (orgnr, org.nr). The architecture's whole bet is that the second country is one folder plus one import line. Here's the proof, and the invitation.

The template already ships

src/registry_mcp/registries/xx/ is a fake country that is fully wired up. Copy it to registries/<cc>/ and fill in six steps — its module docstring is the recipe.

The interface is four methods

class Registry(ABC):
    country = "SE"; registry = "bolagsverket"
    id_scheme = "organisationsnummer"; id_example = "5560212524"
    # + name, id_description, source_url, license, is_stub

    def validate_id(self, id: str) -> str: ...          # sync, pure
    async def lookup(self, id: str) -> CompanyReport: ...
    async def search(self, name: str, limit: int = 10) -> SearchResult: ...
    def deadlines(self, report, today: date) -> list[Deadline]: ...

That's all you implement. lookup/search are async because they do network I/O; validate_id and deadlines are sync and pure — deadlines takes today as a parameter precisely so it's testable with no clock.

You don't write the response documents. Registry.validate() and Registry.deadline_report() are concrete base-class methods that wrap your four primitives into the same ValidationResult and DeadlineReport every other country emits. New country, identical JSON, both surfaces, for free.

Then register(SeRegistry()) at the bottom of your module, and one line in registries/__init__.py:

from registry_mcp.registries import se as se

That import is the only shared file you touch, and it's outside core/.

Stubs are hidden, not absent

Set is_stub = True while you build. list_countries() skips you:

{"countries": [{"country": "NO", "registry": "brreg", "is_stub": false}]}

Set REGISTRY_MCP_INCLUDE_STUBS=1 and the same tool shows your work in progress:

{"countries": [
  {"country": "NO", "registry": "brreg", "is_stub": false},
  {"country": "XX", "registry": "example", "id_scheme": "example_number",
   "id_example": "12345678", "is_stub": true}
]}

So /v1/countries never advertises a country that can't answer, while the abstraction stays testable. And it really is live — XX's validate_id works the day you write it:

{"country": "XX", "id_scheme": "example_number", "input": "12345678",
 "valid": true, "normalized": "12345678", "formatted": null}

while the parts you haven't built yet fail honestly, with a hint:

{"error": {"code": "not_implemented",
  "message": "lookup is not implemented: XX is the example template, not a real registry.",
  "hint": "Call list_countries to see the countries that are actually supported.",
  "country": "XX", "registry": "example"}}

What a PR needs

Fixtures captured from the live API — two or three real entities, saved as JSON, so tests don't hit the network.
Tests, including a numbered rules list for your country's deadlines in the style of Norway's.
rules_markdown() — the prose an agent reads once instead of rediscovering your legal forms one call at a time.
is_stub = False, and your import line.

Good first targets

Denmark, CVR — open, well-documented API; probably the easiest. Sweden, Bolagsverket. Both are close enough to Norway that the models fit, far enough that they'll test the abstraction honestly.

MIT: https://github.com/foretak/registry-mcp — open an issue with your country code and claim it.

Validate and enrich a spreadsheet of Norwegian org.nrs with one MCP server

fargerod-dotcom — Fri, 04 Sep 2026 18:27:08 +0000

Every finance team has this file: a supplier column of organisasjonsnummer (orgnr, org.nr) typed in by hand. Some are wrong. registry-mcp checks them against Brønnøysundregistrene / Enhetsregisteret (brreg) and fills in the rest.

claude mcp add registry-mcp --transport http https://api.foretak.dev/mcp
# or locally, over stdio: uvx registry-mcp

The prompt

Here's suppliers.csv. Check every org.nr, drop the ones that aren't real companies, and add legal form, status, VAT number and city.

suppliers.csv:

org_nr,supplier_name
923609016,Equinor
833285602,El Ansari Konsult
974760673,Registerenheten i Brønnøysund
833286602,Nordvik Regnskap
999999999,Fjord Design
923 609 016,Equinor (duplicate row)

Step 1 — `validate_company_id` on every row

It does no network call, so run it on all six before spending a lookup on any. Two rows are interesting:

{
  "input": "923 609 016",
  "valid": true,
  "normalized": "923609016",
  "formatted": "923 609 016"
}

{
  "input": "833286602",
  "valid": false,
  "normalized": null,
  "reason": "'833286602' is not a valid Norwegian organisasjonsnummer.",
  "hint": "An organisasjonsnummer is nine digits with a MOD11 check digit, e.g. 923609016. If you have a company name instead, call search_company."
}

normalized is the dedupe key — the spaced row and row 1 are the same company. And valid: false is a plain answer, not an exception: MOD11 catches the transposed digit in 833286602. That's one lookup saved and one bad supplier caught for free.

Step 2 — `lookup_company` on the survivors

Five rows, five calls, ~60 lines of Python (enrich.py):

org_nr,supplier_name,valid,normalized,name,legal_form,status,vat_registered,vat_number,employees,city,problem
923609016,Equinor,True,923609016,EQUINOR ASA,Public limited company,active,True,NO923609016MVA,21239,STAVANGER,
833285602,El Ansari Konsult,True,833285602,EL ANSARI KONSULT,Sole proprietorship,active,True,NO833285602MVA,,OSLO,
974760673,Registerenheten i Brønnøysund,True,974760673,REGISTERENHETEN I BRØNNØYSUND,Organisational unit of a public body,active,False,,492,BRØNNØYSUND,not VAT-registered — do not accept MVA on an invoice
833286602,Nordvik Regnskap,False,,,,,,,,,'833286602' is not a valid Norwegian organisasjonsnummer.
999999999,Fjord Design,True,999999999,,,,,,,,not_found: No entity with organisasjonsnummer 999999999 exists in Enhetsregisteret.
923 609 016,Equinor (duplicate row),True,923609016,EQUINOR ASA,Public limited company,active,True,NO923609016MVA,21239,STAVANGER,

Three different failures, three different fixes, and the problem column keeps them apart:

833286602 — never a valid number. Someone mistyped it. Search by name.
999999999 — passes MOD11, but lookup_company raises not_found. Well-formed is not the same as real; only the network call can tell you.
974760673 — a real, active entity that is simply not in Merverdiavgiftsregisteret. If it sends you an invoice with MVA on it, that's the finding.

One column deserves a note. EL ANSARI KONSULT's employees is blank because the API returned null — the register publishes no figure. null is not 0; the report carries employees_reported so you can tell "unknown" from "zero" instead of writing a false headcount into your spreadsheet.

Source: Enhetsregisteret, NLOD 2.0. Same JSON over MCP and REST.
Repo: https://github.com/foretak/registry-mcp

Every filing deadline a Norwegian AS faces this quarter, in one tool call

fargerod-dotcom — Fri, 04 Sep 2026 18:26:58 +0000

"What do we owe Skatteetaten and Regnskapsregisteret next?" is a question your agent should not answer from memory. registry-mcp computes it from Brønnøysundregistrene / Enhetsregisteret (brreg) facts, by organisasjonsnummer (orgnr, org.nr).

claude mcp add registry-mcp --transport http https://api.foretak.dev/mcp
# or locally, over stdio: uvx registry-mcp

The prompt

Today is 1 October 2026. For org.nr 923 609 016, list every statutory filing deadline coming up, with the date and why it applies.

The call

company_deadlines(id="923609016", today="2026-10-01")

Pass today explicitly. Deadlines are computed, never fetched, so the same entity and the same today always give the same list — which is what makes the answer testable instead of "whatever the server clock said".

{
  "company_name": "EQUINOR ASA",
  "today": "2026-10-01",
  "deadlines": [
    {
      "kind": "payroll_report",
      "name": "Monthly payroll report (A-melding)",
      "local_name": "A-melding",
      "authority": "NAV / Skatteetaten (A-ordningen)",
      "statutory_date": "2026-10-05",
      "due_date": "2026-10-05",
      "rolled_forward": false,
      "period_label": "2026-09",
      "recurrence": "monthly",
      "days_until": 4,
      "applies_because": "This entity has reported employees and must file the monthly payroll report (a-melding) with NAV/Skatteetaten."
    },
    { "kind": "vat_return", "due_date": "2026-10-12", "statutory_date": "2026-10-10", "rolled_forward": true, "period_label": "2026 term 4 (Jul–Aug)", "days_until": 11 },
    { "kind": "shareholder_register_statement", "due_date": "2027-02-01", "statutory_date": "2027-01-31", "rolled_forward": true, "days_until": 123 },
    { "kind": "tax_return", "due_date": "2027-05-31", "days_until": 242 },
    { "kind": "general_meeting", "due_date": "2027-06-30", "days_until": 272 },
    { "kind": "annual_accounts", "due_date": "2027-08-02", "statutory_date": "2027-07-31", "rolled_forward": true, "days_until": 305 }
  ],
  "notes": [
    "Filing deadlines are computed assuming a calendar-year accounting period. A company with a deviating accounting year (avvikende regnskapsår) will have different actual dates, and Enhetsregisteret does not publish which companies those are."
  ]
}

Two deadlines fall inside Q4: the a-melding on 5 October and the VAT return on 12 October.

Quote due_date, not statutory_date. The VAT return's statutory date is 10 October — a Saturday. due_date is 12 October and rolled_forward: true says why. Same for the annual accounts: 31 July 2027 is a Saturday, so the real date is 2 August.

applies_because is the citation. Nothing here is a legal-form guess: the a-melding appears because the entity reports employees, the VAT return because it's in Merverdiavgiftsregisteret. The docstring's rule is to quote that sentence rather than presenting a date as unconditional fact.

Read notes before you send it to anyone. The list assumes a calendar-year accounting period, because Enhetsregisteret does not publish who has a deviating one. Every annual date above inherits that assumption.

An empty deadlines list is a real answer too — a bankrupt, deleted or compulsorily-liquidated entity, a sub-unit, or a legal form the module has not classified. notes says which, and the service would rather omit an obligation than invent one.

Source: Enhetsregisteret, NLOD 2.0. Same JSON over MCP and REST.
Repo: https://github.com/foretak/registry-mcp

Check a Norwegian supplier is VAT-registered before you pay the invoice

fargerod-dotcom — Fri, 04 Sep 2026 15:13:13 +0000

Your agent is about to approve an invoice charging 25% MVA. Is the supplier actually in Merverdiavgiftsregisteret? registry-mcp answers from Brønnøysundregistrene / Enhetsregisteret (brreg), by organisasjonsnummer (orgnr, org.nr).

claude mcp add registry-mcp --transport http https://api.foretak.dev/mcp
# or locally, over stdio: uvx registry-mcp

The prompt

Invoice 2026-0417 from EL ANSARI KONSULT, org.nr 833 285 602, charges NOK 4 000 + 25% MVA. Before I pay: is this supplier VAT-registered, and is the business active?

The call

lookup_company(id="833285602")

{
  "name": "EL ANSARI KONSULT",
  "legal_form_code": "ENK",
  "legal_form": "Sole proprietorship",
  "status": "active",
  "is_active": true,
  "vat_registered": true,
  "vat_registered_at": "2024-04-15",
  "vat_number": "NO833285602MVA",
  "registers": {
    "foretaksregisteret": false,
    "mvaregisteret": true
  },
  "source_url": "https://data.brreg.no/enhetsregisteret/api/enheter/833285602",
  "license": "NLOD 2.0"
}

Four fields settle it:

vat_registered: true — the answer.
registers.mvaregisteret — the same fact as the register publishes it, next to the other four registers. Cite this one.
vat_number — NO833285602MVA must match the number printed on the invoice. If it doesn't, stop.
vat_registered_at: "2024-04-15" — an invoice dated before this charged VAT the supplier wasn't entitled to collect.

status: "active" is the second half of the question. A bankrupt or deleted entity comes back with a different status and a notes entry saying so — the tool docstring is blunt about it: "Read the returned notes before acting on the result."

The two ways this says no

Malformed number. validate_company_id is free and does no network call, so run it on invoice input first:

{
  "input": "833286602",
  "valid": false,
  "normalized": null,
  "reason": "'833286602' is not a valid Norwegian organisasjonsnummer.",
  "hint": "An organisasjonsnummer is nine digits with a MOD11 check digit, e.g. 923609016. If you have a company name instead, call search_company."
}

valid: false is a normal 200-shaped answer, never an exception. One transposed digit is the usual cause. Fix it, or call search_company with the supplier's name — retrying the same string will not help.

Well-formed, but nobody's. 999999999 passes the MOD11 check and still isn't a company:

{
  "error": {
    "code": "not_found",
    "message": "No entity with organisasjonsnummer 999999999 exists in Enhetsregisteret.",
    "hint": "The number is well-formed, so it may never have been issued or the entity may have been deleted. Call search_company with the company name instead."
  }
}

A valid orgnr is not an existing company. not_found means never issued, or deleted — hold the payment and ask a human.

Source: Enhetsregisteret, NLOD 2.0. Same JSON over MCP and REST.
Repo: https://github.com/foretak/registry-mcp

DEV Community: fargerod-dotcom

Check a UK supplier at Companies House from Claude Code — and the same tool works for Norway

The prompt

The call

The half that's actually useful

Two things that will trip your agent

Add your country's company registry to registry-mcp in an afternoon

The template already ships

The interface is four methods

Stubs are hidden, not absent

What a PR needs

Good first targets

Validate and enrich a spreadsheet of Norwegian org.nrs with one MCP server

The prompt

Step 1 — validate_company_id on every row

Step 2 — lookup_company on the survivors

Every filing deadline a Norwegian AS faces this quarter, in one tool call

The prompt

The call

Check a Norwegian supplier is VAT-registered before you pay the invoice

The prompt

The call

The two ways this says no

Step 1 — `validate_company_id` on every row

Step 2 — `lookup_company` on the survivors