> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmium.de/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> KI-Agenten über das Model Context Protocol mit Firmium-Unternehmensdaten für Österreich, Deutschland und die Schweiz verbinden.

Der Firmium MCP-Server lässt KI-Agenten (Claude, ChatGPT oder eigene) **DACH-Unternehmensdaten**
abfragen — Stammdaten, Management, Gesellschafter, Finanzen, den Beziehungsgraph und einen
Änderungs-Feed — direkt über das [Model Context Protocol](https://modelcontextprotocol.io).

Es ist die erste MCP-native Quelle für österreichische, deutsche und Schweizer Unternehmensdaten:
keine statischen Datensätze, sondern **Beziehungen und Veränderungen über die Zeit**, jedes Feld
mit seiner Herkunft markiert, damit ein Agent weiß, worauf er sich verlassen kann.

## Endpoint

```
https://mcp.firmium.de/mcp/
```

Transport ist **Streamable HTTP**. Authentifizierung ist **OAuth 2.1** — dein MCP-Client findet den
Server, registriert sich automatisch (Dynamic Client Registration) und durchläuft den
PKCE-Authorization-Flow. Kein manuelles Schlüssel-Handling im Client.

## Schnellstart

<Tabs>
  <Tab title="Claude Desktop / Code">
    Server hinzufügen; Claude öffnet einen Browser zur Autorisierung:

    ```json theme={null}
    {
      "mcpServers": {
        "firmium": {
          "type": "http",
          "url": "https://mcp.firmium.de/mcp/"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Beliebiger MCP-Client">
    Den Client auf `https://mcp.firmium.de/mcp/` richten. Beim ersten Verbinden läuft OAuth 2.1
    (Discovery → Dynamic Registration → PKCE) und der Bearer-Token wird gespeichert.
  </Tab>
</Tabs>

## Authentifizierung & Scopes

Tokens werden vom Firmium-Authorization-Server ausgestellt und tragen einen oder mehrere Scopes:

| Scope                                | Erlaubt                                                                                       |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `companies:read`                     | Unternehmensdaten: Profil, Management, Gesellschafter, Finanzen, Netzwerk, Änderungen, Risiko |
| `prospecting:read`                   | Firmensuche per Filter (Prospecting / Lead-Generierung)                                       |
| `watchdogs:read` / `watchdogs:write` | Monitoring-Agenten (Watchdogs) lesen / anlegen                                                |

Ein Aufruf ohne gültigen Token oder ohne den vom Tool benötigten Scope wird mit einer klaren
Fehlermeldung abgelehnt. Ein Entzug des Zugriffs wirkt sofort.

## Tools

Vier Tools (read-only außer `manage_watchdogs` `create`), die strukturiertes JSON zurückgeben.

| Tool                 | Argumente                                                     | Liefert                                                                    |
| -------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `search_company`     | `query`, `country?`, `limit?`                                 | Gerankte Treffer mit Firmium-`uuid`                                        |
| `get_company`        | `uuid`, `sections?` (+ Section-Parameter)                     | Die angefragten `sections` eines Unternehmens                              |
| `discover_companies` | `filters?`, `query?`, `similar_to_uuid?`, `limit?`, `offset?` | Firmen, die zum ICP passen (oder ähnlich zu `similar_to_uuid`), mit `uuid` |
| `manage_watchdogs`   | `action` (list/events/create), …                              | Monitoring-Agenten und ihre Signale                                        |

Das `get_company`-Tool liefert nur die angefragten `sections` (Default `overview`). Sections:
`overview`, `management`, `shareholders`, `ownership_tree`, `financials`, `financial_indicators`,
`network`, `changes`, `sanctions`, `insolvency`, `ip`, `industry`, `publications`, `bank_accounts`,
`employees`, `alerts`.

### Vertrauenssignale (warum Agenten sich darauf verlassen können)

Jede Antwort macht Herkunft und Lücken explizit, damit ein Agent eine Lücke nie für eine Tatsache hält:

* **Herkunft** — Beziehungen und Kanten sind `official_registry` (im Handelsregister erfasst) oder
  `derived` (abgeleitet). Abgeleitete Daten tragen `confidence: low`.
* **Datenlücken** — eine fehlende Section meldet `availability`:
  * `present` — Daten sind enthalten,
  * `not_present` — wir haben die Quelle geprüft, es gibt keine,
  * `not_loaded` — wir haben sie noch nicht erhoben.

## End-to-End-Beispiel

> **Agent-Prompt:** „Wer führt die Muster Technik GmbH, und wächst sie?"

```text theme={null}
1. search_company(query="Muster Technik GmbH")
   → { count: 1, results: [{ uuid: "…", name: "Muster Technik GmbH", status: "Active" }] }

2. get_company(uuid="…", sections=["management", "financials"])
   → { company: { name: "Muster Technik GmbH", status: "Active" },
       sections: {
         management: { items: [{ party: { full_name: "Max Muster" },
                                 relationship_type: "managing_director",
                                 provenance: { source: "official_registry", confidence: "high" } }] },
         financials: { years: [{ year: 2024, revenue: "1500000.00" }, …],
                       data_status: { availability: "present" } } } }
```

## Preise

Nutzungsbasiert: du zahlst pro erfolgreichem Tool-Call. Fehlgeschlagene und rate-limitierte Calls
werden nicht berechnet. Jeder Kunde hat ein Budget pro Minute und pro Tag. Für Volumen-Staffeln
sprich uns an.

## Onboarding

1. Zugang anfragen auf [firmium.de](https://www.firmium.de) — du bekommst ein Firmium-Konto.
2. `https://mcp.firmium.de/mcp/` zu deinem MCP-Client hinzufügen.
3. Beim ersten Verbinden im Browser autorisieren (OAuth 2.1, keine manuellen Schlüssel).
4. Tools aufrufen — die Nutzung wird automatisch gemetert.