> ## 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

> Connect AI agents to Firmium company intelligence for Austria, Germany and Switzerland over the Model Context Protocol.

The Firmium MCP server lets AI agents (Claude, ChatGPT, or your own) query
**DACH company intelligence** — master data, management, shareholders, financials,
the relationship graph and a change feed — directly, over the
[Model Context Protocol](https://modelcontextprotocol.io).

It is the first MCP-native source for Austrian, German and Swiss company data: not
static records, but **relationships and changes over time**, every field tagged with
its provenance so an agent knows what to trust.

## Endpoint

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

Transport is **Streamable HTTP**. Authentication is **OAuth 2.1** — your MCP client
discovers the server, registers automatically (Dynamic Client Registration), and
runs the PKCE authorization flow. No manual key handling in the client.

## Quickstart

<Tabs>
  <Tab title="Claude Desktop / Code">
    Add the server; Claude opens a browser to authorize:

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

  <Tab title="Any MCP client">
    Point the client at `https://mcp.firmium.de/mcp/`. On first connect it performs
    OAuth 2.1 (discovery → dynamic registration → PKCE) and stores the bearer token.
  </Tab>
</Tabs>

## Authentication & scopes

Tokens are issued by the Firmium authorization server and carry one or more scopes:

| Scope                                | Grants                                                                              |
| ------------------------------------ | ----------------------------------------------------------------------------------- |
| `companies:read`                     | Company data: profile, management, shareholders, financials, network, changes, risk |
| `prospecting:read`                   | Company discovery by filters (prospecting / lead generation)                        |
| `watchdogs:read` / `watchdogs:write` | Read / create monitoring agents (watchdogs)                                         |

A call without a valid token, or without the scope a tool requires, is rejected with
a clear error. Revoking access takes effect immediately.

## Tools

Four tools (read-only except watchdog `create`), returning structured JSON.

| Tool             | Arguments                                 | Returns                                |
| ---------------- | ----------------------------------------- | -------------------------------------- |
| `search_company` | `query`, `country?`, `limit?`             | Ranked matches with Firmium `uuid`     |
| `company`        | `uuid`, `sections?` (+ section params)    | The requested `sections` of a company  |
| `prospecting`    | `filters?`, `query?`, `limit?`, `offset?` | Companies matching an ICP, with `uuid` |
| `watchdog`       | `action` (list/events/create), …          | Monitoring agents and their signals    |

The `company` tool returns only the `sections` you request (default `overview`).
Sections: `overview`, `management`, `shareholders`, `ownership_tree`, `financials`,
`financial_indicators`, `network`, `changes`, `sanctions`, `insolvency`, `ip`,
`industry`, `publications`, `bank_accounts`, `employees`, `alerts`.

### Trust signals (why agents can rely on this)

Every response is explicit about provenance and gaps, so an agent never mistakes a
gap for a fact:

* **Provenance** — relationships and edges are `official_registry` (recorded in a
  business register) or `derived` (inferred). Derived data carries `confidence: low`.
* **Data gaps** — a missing section reports `availability`:
  * `present` — data is included,
  * `not_present` — we checked the source and there is none,
  * `not_loaded` — we have not collected it yet.

## End-to-end example

> **Agent prompt:** "Who runs Muster Technik GmbH, and is it growing?"

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

2. 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" } } } }
```

## Pricing

Usage-based: you pay per successful tool call. Failed and rate-limited calls are not
billed. Each customer has a per-minute and per-day request budget. Contact us for
volume tiers.

## Onboarding

1. Request access at [firmium.de](https://www.firmium.de) — you get a Firmium account.
2. Add `https://mcp.firmium.de/mcp/` to your MCP client.
3. Authorize in the browser on first connect (OAuth 2.1, no manual keys).
4. Start calling tools — usage is metered automatically.