# Handelsregister > German Handelsregister + Austrian Firmenbuch for AI agents: master data, financials & ratios. - name: io.github.jkbngb/handelsregister - version: 1.0.1 - connection class: R0 (autonomous) - trust: 94/100 - quality: 89/100 (good) - owner: not claimed - descriptor: https://api.protogrid.dev/v1/servers/io.github.jkbngb%2Fhandelsregister - tools: https://api.protogrid.dev/v1/servers/io.github.jkbngb%2Fhandelsregister/tools **An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe. ## Connection (mcpServers) ```json { "mcpServers": { "handelsregister": { "type": "http", "url": "https://register.agentic-firmenbuch.at/mcp", "headers": { "X-API-Key": "${X_API_KEY}" } } } } ``` Placeholders to fill: `${X_API_KEY}`. ## Trust - hygiene: 100 - liveness: 100 - freshness: 100 - provenance: 80 - drivers: +repository +namespace-matches-repo +reachable +uptime-100% +updated-12d-ago - Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed. ## Quality 89/100 (good) ### protocol: 100 (weight 25) - pass `protocol.modern`: supports 2026-07-28 (server/discover) - pass `protocol.stateless`: answers without a session - pass `protocol.transport`: streamable HTTP - pass `protocol.list_ttl`: tool list is cacheable (ttlMs 300000) ### authorization: n/a (weight 15) - n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth - n/a `auth.secret_in_url`: no templated URL ### tool hygiene: 86 (weight 30) - pass `tools.descriptions`: every tool has a description - warn `tools.description_length`: 7 tools have descriptions over 1,024 characters, which crowds the context - pass `tools.schemas`: every tool has an object input schema - pass `tools.annotations`: 19 of 19 tools declare readOnlyHint or destructiveHint - pass `tools.directory_hints`: every tool declares readOnlyHint, destructiveHint, idempotentHint and openWorldHint - warn `tools.token_cost`: about 9,769 tokens to load every tool - pass `tools.api_dump`: tools are not a one-to-one API dump ### stability: 75 (weight 15) - warn `stability.changes`: 9 tool changes in 30 days - pass `stability.rug_pull`: no tool changed its meaning under the same name ### dependencies: n/a (weight 15) - n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package - tools: 19, about 9,769 tokens to load them all - tool set hash: 04c5f7daeade72fd7c12fd3cb4a5cde5 - tools last changed: 2026-10-11T21:32:43.157Z - badge: [![protogrid quality](https://protogrid.dev/badge/io.github.jkbngb/handelsregister.svg)](https://protogrid.dev/servers/io.github.jkbngb/handelsregister) - Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed. ### Tool changes - 2026-10-11 `benchmark_company` added - Benchmark ONE company against its size-class cohort: headline metrics, percentile ranks and the nearest peers. Read-only. Parameters: - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only (needs parsed financials); a German id returns a clear error. - n (optional, default 10): how many nearest peers to return. Returns the AT backend's benchmark payload plus ``country`` and the prefixed ``company_id``: headline figures, ``percentiles`` within the UGB size class, and the nearest peers with a recency note. For a cross-border meaning-based peer set use find_peers with cross_border=true. - 2026-10-11 `get_cohort_summary` added - Aggregate statistics for a cohort of companies, per country. Read-only. Parameters: - dimension (required): "gkl" (UGB size class, AT only), "bundesland", or "legal_form" (alias size_gkl -> gkl). - value (required): the cohort value (e.g. bundesland "Wien", legal_form "GmbH"). - country (optional, default "all"): "AT" | "DE" | "all". Returns {countries, dimension, value, per_country, notices}. ``bundesland`` and ``legal_form`` fan out to every supporting country; ``gkl`` is Austrian-only (no German size-class facet) and excludes DE with a notice. Each country's own cohort payload sits under ``per_country`` (the registers aggregate different metrics, so they are reported side by side, not force-merged). For one company use get_company_details; for a filtered list use search_companies. - 2026-10-11 `list_sectors` added - The value lists for filtering - legal forms, size classes - and, with a query word, the matching OENACE sectors with the exact nace_* filter to use. Read-only. Parameters: - query (optional): a category word (e.g. "Brauerei", "software"); returns ``matches`` with each sector's level, code, label and the nace_* filter value for search_companies. Omitted: the legal-form and size-class value lists with counts. Served from the Austrian backend; the industry codes are OENACE == WZ == NACE Rev. 2, identical for both countries, so a resolved code also filters the German register. The value lists and counts themselves are Austrian (a notice says so). It returns no company data - call it once up front to resolve a filter value. - 2026-10-11 `get_document_text` added - Extracted text of ONE Austrian filing document, by its document key. Read-only. Parameters: - doc_key (required): the document_ref from list_documents (an Austrian filing key). - max_chars (optional, default 40000, clamped 1000-120000): truncation ceiling. Returns {doc_key, text, truncated, ...} with the filing's Stichtag for citation. Austria only today. Use list_documents to discover the key; for the German official register abstract use get_document. - 2026-10-11 `list_documents` added - Chronology of a company's filing documents (metadata, newest first). Read-only. Parameters: - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only; for the German official register abstract use get_document with a "DE:" id instead. Returns the AT backend's document list plus ``country`` and the prefixed ``company_id``: each entry has type, Stichtag, financial_year, document_ref, format and whether it was parsed. Feed a document_ref to get_document_text for the extracted text. - 2026-10-11 `get_full_record` added - The complete multi-year record for ONE company: every balance-sheet and P&L position's full per-year history, completeness flags and lineage. Read-only. The heaviest read - use get_company_details for a normal profile. Parameters: - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only today; a German id returns a clear error (Germany does not serve a full parsed record yet). Returns the AT backend's full-record payload plus ``country`` and the prefixed ``company_id``. Includes unknown-code passthrough and the filing years covered. - 2026-10-11 `get_company_history` added - Per-year financial-metric history for ONE company, routed by its unified id. Read-only. Parameters: - company_id (required): "AT:{fnr}" or "DE:{court}_{type}{number}" (bare national ids accepted), from a search card. - metrics (optional, AT only): names of the metrics to return (e.g. bilanzsumme, umsatzerloese, equity_ratio); omitted = all. Ignored for DE. Returns the backend's history payload plus ``country`` and the prefixed ``company_id``: per-metric {year: value} with latest/latest_year. AT serves the parsed Bilanz/GuV/ratio series. DE serves the parsed Jahresabschluss series where the company has filed and its Bundesland is loaded; an empty series means not-filed or not-yet- loaded, never zero (see get_company_details financials.reporting_status). For a single snapshot use get_company_details; for the complete record use get_full_record. - 2026-10-04 `get_document` changed (description) - before: On-demand official register PDF for ONE German company. Read-only. Parameters: - company_id (required): "DE:{court}_{type}{number}" (e.g. "DE:D2601_HRB135076"); a bare German id works too. Austria is not supported here (its document flow is different). - kind (optional): "AD" = Aktueller Abdruck (current register extract, default), "CD" = Chronologischer Abdruck. Fetches the official PDF from handelsregister.de on demand (first call ~10 s, then cached) and returns a short-lived download link: {company_id, kind, url, bytes, cached, available, source, expires_at, expires_in_seconds}. When the register holds nothing for that kind, ``available`` is false with a ``note`` (never a dead link). A non-DE id returns an error. - after: On-demand official register document for ONE German company. Read-only. Parameters: - company_id (required): "DE:{court}_{type}{number}" (e.g. "DE:D2601_HRB135076"); a bare German id works too. Austria is not supported here (its document flow is different). - kind (optional): "AD" = Aktueller Abdruck (current register extract, default) or "CD" = Chronologischer Abdruck -- the official Handelsregister abstract PDF; or "JA" = Jahresabschluss -- the company's newest official annual financial statement as published by the Unternehmensregister (served as the official HTML document, no PDF exists at the source). Returns a short-lived download link: {company_id, kind, url, bytes, cached, available, source, expires_at, expires_in_seconds} (plus year, stichtag for "JA"). AD/CD are fetched from handelsregister.de on demand (first call ~10 s, then cached); JA is served from the stored official publication. When the register holds nothing for that kind, ``available`` is false with a ``note`` (never a dead link). A non-DE id returns an error. - 2026-09-23 `get_document` added - On-demand official register PDF for ONE German company. Read-only. Parameters: - company_id (required): "DE:{court}_{type}{number}" (e.g. "DE:D2601_HRB135076"); a bare German id works too. Austria is not supported here (its document flow is different). - kind (optional): "AD" = Aktueller Abdruck (current register extract, default), "CD" = Chronologischer Abdruck. Fetches the official PDF from handelsregister.de on demand (first call ~10 s, then cached) and returns a short-lived download link: {company_id, kind, url, bytes, cached, available, source, expires_at, expires_in_seconds}. When the register holds nothing for that kind, ``available`` is false with a ``note`` (never a dead link). A non-DE id returns an error. Full history: https://api.protogrid.dev/v1/servers/io.github.jkbngb%2Fhandelsregister/changes ## Remotes - https://register.agentic-firmenbuch.at/mcp (streamable-http, auth none, reachable true, uptime30d 1) ## Packages _none_ ## Tools (19) - `benchmark_company`: Benchmark ONE company against its size-class cohort: headline metrics, percentile ranks and the nearest peers. Read-only. Parameters: - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only (needs parsed financials); a German id returns a clear error. - n (optional, default 10): how many nearest peers to return. Returns the AT backend's benchmark payload plus ``country`` and the prefixed ``company_id``: headline figures, ``percentiles`` within the UGB size class, and the nearest peers with a recency note. For a cross-border meaning-based peer set use find_peers with cross_border=true. - `describe_fields`: Schema self-description: the unified id scheme, which filters exist, which countries support which capability, and each country's own field catalog. Read-only. Parameters: - country (optional, default "all"): "AT" | "DE" | "all" - whose field catalogs to include. Returns {id_scheme, capabilities, countries, countries_unavailable}. ``id_scheme`` documents the unified company_id ("AT:123456a", "DE:D2601_HRB135076"; bare national ids are accepted, responses always return the prefixed form). ``capabilities`` is the per-country capability matrix including each country's supported unified filters - a filter absent for a country is applied to the others and reported in a notice, never silently dropped. ``countries`` carries each backend's own describe_fields payload (code tables, null rules, tool tiers). Call once up front when unsure which filter or tool to use; it returns no company data itself. - `export_companies_csv`: Export a matched company set as downloadable CSV files (lead lists). Read-only over company data; each call writes new short-lived export files (auto-deleted after ~1 day). Parameters: - filters (optional): EXACTLY the same unified filters as search_companies. - sort (optional): same as search_companies (applies where the country supports the field). - max_rows (optional, default 1000, max 10000): per-country row ceiling. - country (optional, default "all"): "AT" | "DE" | "all". Returns {countries: {: {download_url, rows, columns, ...}}, notices}. ONE CSV per country (semicolon-separated, UTF-8 BOM, Excel-ready): each register exports its own column set - DE files have no financial columns yet (blank would wrongly read as zero). Download links are signed and valid ~60 minutes. A filter a country does not support excludes that country with a notice, like search_companies. For browsing/ranking on screen use search_companies instead. - `find_peers`: Companies most similar to a given one - optionally ACROSS THE BORDER. Read-only. Parameters: - company_id (required): "AT:{fnr}" or "DE:{court}_{type}{number}" (bare national ids accepted), from a search card. - n (optional, default 10): how many peers per country. - cross_border (optional, default false): when true, additionally returns ``peers_abroad`` - the companies in the OTHER country whose registered purpose is semantically closest to the reference company's activity text. Returns {company_id, country, peers_home, home_envelope, peers_abroad?, notes}. ``peers_home`` uses the home register's own peer logic (AT: same size class, same industry preferred, nearest by Bilanzsumme; DE: semantic-first by registered purpose). ``peers_abroad`` is a MEANING-based match, not a size or financial benchmark - the honest cross-border comparison given the countries' different data depth (see notes). Empty peers_home means the id is unknown or the company lacks the data its register ranks by. For a strict filtered list use search_companies; for aggregates use the country server's cohort tools. - `get_cohort_summary`: Aggregate statistics for a cohort of companies, per country. Read-only. Parameters: - dimension (required): "gkl" (UGB size class, AT only), "bundesland", or "legal_form" (alias size_gkl -> gkl). - value (required): the cohort value (e.g. bundesland "Wien", legal_form "GmbH"). - country (optional, default "all"): "AT" | "DE" | "all". Returns {countries, dimension, value, per_country, notices}. ``bundesland`` and ``legal_form`` fan out to every supporting country; ``gkl`` is Austrian-only (no German size-class facet) and excludes DE with a notice. Each country's own cohort payload sits under ``per_country`` (the registers aggregate different metrics, so they are reported side by side, not force-merged). For one company use get_company_details; for a filtered list use search_companies. - `get_company_details`: Full profile for ONE company, routed by its unified id. Read-only. Parameters: - company_id (required): "AT:{fnr}" (e.g. "AT:123456a") or "DE:{court}_{type}{number}" (e.g. "DE:D2601_HRB135076"); bare national ids are accepted too. Take it from a search card's ``company_id``. - max_signatories (optional, DE only): cap on the served officer list (DE default 15, 0 = all); ignored for AT. Returns the country backend's full profile plus ``country`` and the prefixed ``company_id``. AT: identity, location, per-year Bilanz + GuV, ratios, growth, filings, management, events. DE: identity, seat, Stammkapital, Gegenstand, WZ/NACE classification, managing directors (birth year only) - German financial statements are not covered yet, so never report them as zero or missing. Unknown id -> {error: not_found}. Use search_companies first when you only have a name. - `get_company_history`: Per-year financial-metric history for ONE company, routed by its unified id. Read-only. Parameters: - company_id (required): "AT:{fnr}" or "DE:{court}_{type}{number}" (bare national ids accepted), from a search card. - metrics (optional, AT only): names of the metrics to return (e.g. bilanzsumme, umsatzerloese, equity_ratio); omitted = all. Ignored for DE. Returns the backend's history payload plus ``country`` and the prefixed ``company_id``: per-metric {year: value} with latest/latest_year. AT serves the parsed Bilanz/GuV/ratio series. DE serves the parsed Jahresabschluss series where the company has filed and its Bundesland is loaded; an empty series means not-filed or not-yet- loaded, never zero (see get_company_details financials.reporting_status). For a single snapshot use get_company_details; for the complete record use get_full_record. - `get_coverage`: Dataset coverage and the capability matrix, per country. Read-only. CALL THIS FIRST before concluding that something does not exist in a country. Parameters: - country (optional, default "all"): "AT" | "DE" | "all" - which countries to include. Returns {countries: {: }, capabilities, countries_unavailable}. Each country section is the country backend's own coverage dashboard (AT: parsed-financials counts by format/status; DE: per-Bundesland counts + fill rates - the DE backfill is still running, so a low count means "not crawled yet", not "does not exist"). ``capabilities`` is the machine-readable matrix of what each country supports (financials, documents, events windows, filters); a country that cannot be reached appears under ``countries_unavailable`` with the error instead of failing the whole call. For valid filter values use describe_fields; for per-company data use search_companies. - `get_document`: On-demand official register document for ONE German company. Read-only. Parameters: - company_id (required): "DE:{court}_{type}{number}" (e.g. "DE:D2601_HRB135076"); a bare German id works too. Austria is not supported here (its document flow is different). - kind (optional): "AD" = Aktueller Abdruck (current register extract, default) or "CD" = Chronologischer Abdruck -- the official Handelsregister abstract PDF; or "JA" = Jahresabschluss -- the company's newest official annual financial statement as published by the Unternehmensregister (served as the official HTML document, no PDF exists at the source). Returns a short-lived download link: {company_id, kind, url, bytes, cached, available, source, expires_at, expires_in_seconds} (plus year, stichtag for "JA"). AD/CD are fetched from handelsregister.de on demand (first call ~10 s, then cached); JA is served from the stored official publication. When the register holds nothing for that kind, ``available`` is false with a ``note`` (never a dead link). A non-DE id returns an error. - `get_document_text`: Extracted text of ONE Austrian filing document, by its document key. Read-only. Parameters: - doc_key (required): the document_ref from list_documents (an Austrian filing key). - max_chars (optional, default 40000, clamped 1000-120000): truncation ceiling. Returns {doc_key, text, truncated, ...} with the filing's Stichtag for citation. Austria only today. Use list_documents to discover the key; for the German official register abstract use get_document. - `get_event_stats`: Aggregate counts of register changes by type and region, per country. Read-only. Parameters (all optional): since / until (default last 30 days); bundesland; nace_section; nace_division (AT); legal_form (AT); country ("AT" | "DE" | "all"). Returns {countries, per_country, windows, notices}, each country's block being its own {total, by_type, by_bundesland}. Only AT exposes event statistics today; DE is reported in notices as not yet available (never as zero). For the individual changes use list_events. - `get_full_record`: The complete multi-year record for ONE company: every balance-sheet and P&L position's full per-year history, completeness flags and lineage. Read-only. The heaviest read - use get_company_details for a normal profile. Parameters: - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only today; a German id returns a clear error (Germany does not serve a full parsed record yet). Returns the AT backend's full-record payload plus ``country`` and the prefixed ``company_id``. Includes unknown-code passthrough and the filing years covered. - `get_my_usage`: Your own API-key usage across both registers: call count and weighted compute-units, per tool. Read-only. Parameters: - window (optional, default "today"): "today" | "yesterday" | "month_to_date" | "last_30_days" | "all". Returns only the calling key's own usage (totals + per-tool breakdown) for that window - never another user's data and never the email behind the key. One meter spans AT and DE, since the facade is the single billing point. Use it to check your consumption against the plan's rate limits. - `list_documents`: Chronology of a company's filing documents (metadata, newest first). Read-only. Parameters: - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only; for the German official register abstract use get_document with a "DE:" id instead. Returns the AT backend's document list plus ``country`` and the prefixed ``company_id``: each entry has type, Stichtag, financial_year, document_ref, format and whether it was parsed. Feed a document_ref to get_document_text for the extracted text. - `list_events`: Cross-company, cross-country feed of register CHANGES, newest first - the market-watch / deal-sourcing surface. Read-only. Parameters (all optional, AND-combined): - types: any of the SUPERSET enum - founding, new_registration, deletion, deletion_announced, name_change, seat_change, legal_form_change, capital_change, management_change, management_join, management_leave, gegenstand_change, merger, split, conversion, contribution, consolidation, division, shareholder_capital_change. Each country's feed carries a SUBSET; a type not in a country's feed is skipped for that country (reported in notices), and a country with none of the requested types is excluded. Note new_registration (DE, a discovery date) and founding (AT, a register event) are distinct - see describe_fields. - since / until: ISO dates. Default window: last 30 days. - bundesland: full state name. - nace_section (A-U, both countries); nace_division (AT only); legal_form (AT only). - company_ids: prefixed watchlist; AT filters the whole list, DE filters ONE id at a time (pass a single DE id, or query DE separately). - country: "AT" | "DE" | "all" (default). page (1), page_size (25). Returns {countries, events, per_country, windows, notices}. ``events`` are merged newest-first, each with ``country`` and a prefixed ``company_id``; AT events add before/after values only for the detailed types. ``windows`` states each country's data availability (AT: detailed >= 2026-07-01, coarse >= ~2020; DE: >= 2026-07-30) so an empty stretch is never mistaken for missing data. For aggregate counts use get_event_stats; for one company's history use get_company_details. - `list_sectors`: The value lists for filtering - legal forms, size classes - and, with a query word, the matching OENACE sectors with the exact nace_* filter to use. Read-only. Parameters: - query (optional): a category word (e.g. "Brauerei", "software"); returns ``matches`` with each sector's level, code, label and the nace_* filter value for search_companies. Omitted: the legal-form and size-class value lists with counts. Served from the Austrian backend; the industry codes are OENACE == WZ == NACE Rev. 2, identical for both countries, so a resolved code also filters the German register. The value lists and counts themselves are Austrian (a notice says so). It returns no company data - call it once up front to resolve a filter value. - `ping`: Liveness probe: confirms the unified register server is up. Read-only. Parameters: - check_backends (optional, default false): when true, additionally performs a cheap connection handshake against every configured country backend and reports per-country reachability ("ok" / "unreachable"). Returns {status, server, countries, provenance} - countries maps each configured country code to its backend product name and, with check_backends, its live reachability. Use get_coverage for data completeness; this tool only says whether the service is up. - `search_companies`: Find companies across the Austrian Firmenbuch and the German Handelsregister - START HERE for any company lookup. Read-only. Parameters: - filters (optional): every field optional, AND-combined. Shared core (both countries): name (substring), query (MEANING-based hybrid search over the registered purpose - both countries), status (active|inactive|all, default all), legal_form, bundesland, city, postal_code (prefix; AT PLZ 4-digit, DE 5-digit), near {place | postal_code, radius_km} (radius search, matches from EVERY queried country within the radius - works across the border), nace_section (A-U; OENACE == WZ == NACE Rev. 2, so one industry code filters both countries), gegenstand (literal substring over the registered activity text), manager_name (person search), company_ids (prefixed watchlist, e.g. ["AT:123456a", "DE:D2601_HRB135076"], max 100). AT-only today (see describe_fields capabilities): nace_division/group, size_gkl, bilanzsumme/revenue/equity_ratio/ employees ranges, growth_profile, has_guv(_latest), last_filing_year_min, founded_year_min/max, gf_age_min, event_signal/since/until. DE-only: registergericht, capital_min/max (Stammkapital). Country aliases (geschaeftszweig, oenace_*, wz_section, fnrs, stammkapital_*) are accepted. - sort (optional): {field, descending}. AT fields: bilanzsumme (default), revenue, equity_ratio, employees, last_filing_year, revenue_growth_1y/3y/5y, distance. DE fields: name, register_nummer, capital. A country that cannot sort by the requested field returns its default order (reported in notices). - page (default 1), page_size (default 25). - after (optional): KEYSET paging for bulk extraction - single country only (cursors are per register). Pass "" to start, then the country's next_after from per_country. - exact_count (optional, default false): force exact totals (costs a full scan). - country (optional, default "all"): "AT" | "DE" | "all". Returns {countries, total: {AT, DE, combined}, results, per_country, notices}. ``results`` are compact cards, each with ``country`` and the prefixed ``company_id``; with country="all" the list is AT block then DE block - each country keeps its own ranking (no fake interleave). ``per_country`` carries each register's own envelope (exact totals or lower bounds, applied_filters, relaxations on zero hits, query_mode, next_after). A filter one country does not support excludes that country and says so in ``notices`` - it is never silently dropped; an unreachable backend appears in ``countries_unavailable`` instead of failing the call. Never report a German company's financials as zero - DE financial data is not covered yet (see get_coverage). For one company's full profile use get_company_details; for a downloadable list use export_companies_csv; for dataset completeness use get_coverage. - `search_person`: Find every company a person runs or represents - across BOTH registers in one call (cross-border person search). Read-only. Parameters: - name (required): person name substring, case-insensitive, e.g. "Mustermann". - country (optional, default "all"): "AT" | "DE" | "all". - page_size (optional, default 25): results per country. - status (optional, default "all"): "active" | "inactive" | "all". Returns the merged search_companies envelope ({countries, results, per_country, notices}) plus ``person_query``; every result card carries ``country``, ``company_id`` and the matched manager. AT matches the primary managing director, DE matches all managing directors AND registered signatories. IMPORTANT: matching is by name and the registers publish birth YEAR only - a shared name across companies or countries does not prove the same person (the notice says so; use birth years and context to corroborate). For general company search use search_companies with other filters; manager_name can be combined there too.