KI-Assistenten (MCP)

In Annuva steckt ein Model-Context-Protocol-Server. MCP ist der offene Standard, über den KI-Assistenten Tools aufrufen – damit kann dein Assistent dein Dashboard lesen, Rechnungsentwürfe anlegen, den Abrechnungslauf starten oder Fixkosten buchen, einfach weil du ihn darum bittest.

• Endpunkt: https://<dein-annuva>/api/mcp
• Transport: Streamable HTTP (zustandslos)
• Authentifizierung: dieselben persönlichen API-Tokens wie bei der REST-API: Authorization: Bearer an_…
• Tools: 78 – alles, was die REST-API kann

1. Token anlegen#

Öffne in Annuva Profil → API-Tokens und erstelle ein Token:

• read – der Assistent kann auswerten, aber nie etwas ändern. Er sieht nur die lesenden Tools. Empfohlen für den Einstieg.
• read_write – der Assistent darf auch anlegen, ändern und löschen und Aktionen wie das Ausstellen von Rechnungen ausführen.

Das Token hat die Rechte deines Benutzers. Tools für Einstellungen, Vorlagen und Benutzer gibt es nur mit einem Admin-Konto.

2. Client verbinden#

Claude Code#

claude mcp add --transport http annuva https://annuva.example.com/api/mcp \
    --header "Authorization: Bearer an_…"

Mit claude mcp list prüfst du die Verbindung, danach fragst du einfach in deiner Sitzung.

Claude Desktop#

Claude Desktop startet lokale MCP-Server aus seiner Konfigurationsdatei (Einstellungen → Entwickler → Konfiguration bearbeiten). Die kleine Brücke mcp-remote verbindet sie mit dem HTTP-Endpunkt (braucht Node.js):

{
    "mcpServers": {
        "annuva": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://annuva.example.com/api/mcp",
                "--header",
                "Authorization:${ANNUVA_AUTH}"
            ],
            "env": {
                "ANNUVA_AUTH": "Bearer an_…"
            }
        }
    }
}

Danach Claude Desktop neu starten; Annuva erscheint im Tools-Menü.

Cursor#

In ~/.cursor/mcp.json (oder .cursor/mcp.json im Projekt):

{
    "mcpServers": {
        "annuva": {
            "url": "https://annuva.example.com/api/mcp",
            "headers": {
                "Authorization": "Bearer an_…"
            }
        }
    }
}

VS Code#

In .vscode/mcp.json – VS Code fragt beim ersten Einsatz nach dem Token und speichert es sicher:

{
    "inputs": [
        {
            "type": "promptString",
            "id": "annuva-token",
            "description": "Annuva API token",
            "password": true
        }
    ],
    "servers": {
        "annuva": {
            "type": "http",
            "url": "https://annuva.example.com/api/mcp",
            "headers": {
                "Authorization": "Bearer ${input:annuva-token}"
            }
        }
    }
}

Andere Clients#

Jeder Client, der Streamable HTTP mit eigenem Authorization-Header unterstützt, funktioniert genauso: URL https://<dein-annuva>/api/mcp, Header Authorization: Bearer an_….

3. Fragen#

Die Tool-Namen musst du nicht kennen – beschreib einfach, was du willst:

• „Wie lief dieses Jahr im Vergleich zum letzten?“
• „Welche Kunden kosten mich mehr, als sie bringen?“
• „Erstelle die jährlichen Hosting-Rechnungen für alle Kunden und zeig mir die Entwürfe.“
• „Welche Domains und Verträge verlängern sich in den nächsten 60 Tagen?“
• „Buch die Serverrechnung vom letzten Monat über 38,90 € als Fixkosten.“
• „Erinnere alle Kunden, deren Rechnungen seit mehr als 14 Tagen überfällig sind.“

Gut zu wissen#

• Geldbeträge sind in den Entity-Tools Dezimalzahlen in deiner Währung; die Dashboard-Tools liefern ganzzahlige Cent.
• Ausgestellte Rechnungen kann niemand ändern – auch der Assistent kann sie nur stornieren, was eine Stornorechnung erzeugt.
• Lass dir Entwürfe zeigen, bevor du sie ausstellst oder verschickst. Die meisten Clients fragen nach, bevor ein Tool Daten ändert.
• Alles, was der Assistent liest, geht an den Anbieter deines KI-Modells. Nimm ein Lese-Token, wenn du nur auswerten willst, und prüfe, was dein Anbieter mit den Daten macht.

Alle Tools#

Tools, die mit list_ oder get_ beginnen, lesen nur; alle anderen ändern Daten und brauchen ein read_write-Token.