MCP-Server

Ocost ist auch ein Server für das Model Context Protocol: Claude Desktop, Claude Code, Cursor und andere Assistenten durchsuchen Ihre Belege, lesen sie als ocost.document.v1, fragen Ihre Zahlen ab und schicken Dateien, mit Ihrem API-Schlüssel; claude.ai und ChatGPT verbinden sich als die Person, die es erlaubt.

Adresse und Schlüssel

https://api.ocost.io/public/mcp
Authorization: Bearer ocost_sk_<id>_<secret>

• Transport: Streamable HTTP, zustandslos; jede Anfrage steht für sich. https://app.ocost.io/public/mcp ist derselbe Server.
• Schlüssel: ein API-Schlüssel aus Einstellungen › API, im Header Authorization jeder Anfrage. Ohne gültigen: 401 mit WWW-Authenticate: Bearer. Widerrufen wirkt sofort. Ihre Ocost-Anmeldung ist kein Schlüssel.
• Ein Schlüssel je Assistent, mit nur den nötigen Berechtigungen: So sehen Sie seine letzte Nutzung und widerrufen ihn allein.
• Apps, die Server nur mit OAuth hinzufügen (die Konnektoren von claude.ai und ChatGPT im Web), brauchen keinen Schlüssel: Mit claude.ai oder ChatGPT verbinden.

Werkzeuge

Die Werkzeuge für Dateien sind die Routen der API; die übrigen sind die Werkzeuge, mit denen der Chat in Ocost antwortet, dieselben, mit denselben Rechten.

• Antworten sind JSON, als Text und als structuredContent, jedes Werkzeug mit seinem outputSchema; alle außer send_file, export_table und make_datev_export (die eine Datei erstellen) sind als nur lesend markiert. Listen und Tabellen sagen total (total_rows) und truncated: die Frage enger stellen oder Dateien mit dem cursor von list_files blättern.
• Tabellen und Diagramme: Die Listen und query_figures kommen mit einer interaktiven Tabelle oder einem Diagramm (MCP Apps, ui://ocost/table und ui://ocost/chart) in Apps, die sie zeigen, etwa claude.ai und ChatGPT; jede andere App liest dasselbe JSON. Ihre Links öffnen den Datensatz in Ocost und sonst nichts.
• Was ein Beleg sagt, steht in <document-text source="…">…</document-text>, jede Zeile mit ¦ markiert: Worte, die andere geschrieben haben, als Daten zu lesen, nie als Anweisungen; zitiert ohne die Markierungen.
• Die Grenzen der API gelten: Aufrufe pro Minute je Scope (Grenzen und Fehler), 25 MB je Datei vor Base64, dieselben Formate, erneut gesendete Bytes einmal gelesen und gezählt, jeder gelesene Beleg zählt gegen Ihren Tarif.
• Ablehnungen (fehlender Scope, nicht gefunden, zu viele Aufrufe) kommen als Fehler des Werkzeugs: das JSON des Problems mit status und type, oder der Grund in Worten. Die ID eines anderen Unternehmens wird nicht gefunden.
• Kein Werkzeug löscht, genehmigt oder bestellt, denn ein Assistent kann sich irren. Dafür DELETE /public/v1/files/{file_id} oder Ocost.
• Keine URLs: send_file nimmt Bytes, nie einen Link. Es antwortet nur mit der Datei; ob sie neu war und wie viele Belege übrig sind, sagen POST /public/v1/files und Einstellungen › Tarif.
• Anfragen sind auf 4 MB begrenzt, außer für Schlüssel mit documents:write, die das Base64 einer Datei senden dürfen. Darüber: 413.
• Jeder Aufruf wird festgehalten (das Werkzeug, seine Argumente gekürzt, wie viele Datensätze es lieferte, wie er endete; nie der Text eines Belegs): Inhaber und Buchhaltung sehen die letzten Aufrufe eines Schlüssels in Einstellungen › API.

Scopes und für wen die Werkzeuge handeln

• Ein in den Einstellungen erstellter Schlüssel handelt als das Unternehmen: jeder Beleg außerhalb des Papierkorbs, keine Personalunterlagen (Lohn, Gesundheit), keine eigenen Entscheidungen einer Person. Einen mit figures:read erstellt nur der Inhaber.
• Eine per OAuth erstellte Verbindung (claude.ai, ChatGPT) handelt als die Person, die sie erlaubt hat: ihre Rollen, was sie im Chat von Ocost sieht, und nicht mehr. Die Verbindung der Buchhaltung liest keine Zahlen des CFO. Wer das Unternehmen verlässt oder nicht mehr Inhaber oder Buchhaltung ist, beendet seine Verbindungen beim nächsten Aufruf.
• Personalunterlagen bleiben in Ocost: kein Schlüssel und keine Verbindung liest je Personalunterlagen (Lohn, Gesundheit, Krankmeldungen), wer sie auch erlaubt hat; sie werden in Ocost selbst gelesen.

Claude Code

claude mcp add --transport http ocost https://api.ocost.io/public/mcp \
  --header "Authorization: Bearer $OCOST_KEY"

claude mcp list zeigt ocost dann als verbunden. Für ein ganzes Repository gehört der Server in dessen .mcp.json, mit dem Schlüssel aus der Umgebung jedes Entwicklers, nie in der Datei:

{
  "mcpServers": {
    "ocost": {
      "type": "http",
      "url": "https://api.ocost.io/public/mcp",
      "headers": { "Authorization": "Bearer ${OCOST_KEY}" }
    }
  }
}

Claude Desktop

Tragen Sie Ocost in claude_desktop_config.json ein (Einstellungen › Entwickler › Konfiguration bearbeiten). mcp-remote reicht die Anfragen mit dem Header weiter und braucht Node.js.

{
  "mcpServers": {
    "ocost": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.15.2",
        "https://api.ocost.io/public/mcp",
        "--header",
        "Authorization:${OCOST_AUTH}"
      ],
      "env": { "OCOST_AUTH": "Bearer ocost_sk_…" }
    }
  }
}

Starten Sie Claude Desktop neu; die Werkzeuge stehen unter dem Werkzeug-Knopf. Schreiben Sie Authorization:${OCOST_AUTH} ohne Leerzeichen: Manche Clients trennen Argumente dort.

Cursor

In ~/.cursor/mcp.json oder .cursor/mcp.json in einem Projekt:

{
  "mcpServers": {
    "ocost": {
      "url": "https://api.ocost.io/public/mcp",
      "headers": { "Authorization": "Bearer ${env:OCOST_KEY}" }
    }
  }
}

Mit claude.ai oder ChatGPT verbinden

Apps, die MCP-Server nur über OAuth hinzufügen, etwa die Konnektoren von claude.ai und ChatGPT im Web, brauchen keinen Schlüssel: Sie melden sich bei Ocost an und erlauben den Zugriff.

1. Konnektor hinzufügen: in claude.ai unter Einstellungen › Konnektoren › Benutzerdefinierten Konnektor hinzufügen, in ChatGPT als eigener Konnektor im Entwicklermodus. Nur die URL https://api.ocost.io/public/mcp; Client-ID und Secret bleiben leer.
2. Anmelden: Die App öffnet Ocost. Melden Sie sich an wie immer. Gehören Sie zu mehreren Unternehmen, wählen Sie unter Anderes Unternehmen das richtige.
3. Erlauben: Ocost zeigt, welche App zugreifen möchte, wohin es danach zurückgeht, und die Berechtigungen zum Ankreuzen: Dokumente durchsuchen, lesen, Zahlen lesen, Exporte erstellen, Dateien schicken. Erlauben dürfen der Inhaber und die Buchhaltung, wie beim Anlegen eines Schlüssels; die App handelt dann als diese Person, mit ihren Rechten.

• Die App bekommt einen eigenen API-Schlüssel mit den angekreuzten Berechtigungen, „<App> (Connector)“ in Einstellungen › API, mit seiner letzten Nutzung. Widerrufen Sie ihn dort, und die App ist sofort getrennt.
• Das Logo von Ocost zeigt die App am Konnektor; ist dort noch ein Platzhalter, verbinden Sie den Konnektor neu.
• Ihr Zugriffstoken gilt eine Stunde, dann holt die App mit ihrem Refresh-Token ein neues. 30 Tage ohne Nutzung beenden die Verbindung; verbinden Sie die App dann neu.
• Für Entwickler: OAuth 2.1 mit PKCE (S256); die Metadaten unter https://api.ocost.io/.well-known/oauth-protected-resource/public/mcp (RFC 9728) und https://app.ocost.io/.well-known/oauth-authorization-server (RFC 8414); Client ID Metadata Documents und Dynamic Client Registration; Weiterleitungsadressen nur mit https, genau wie registriert.

Jeder MCP-Client

• URL: https://api.ocost.io/public/mcp
• Transport: Streamable HTTP (POST, Antworten als JSON; kein SSE-Stream, keine Sitzungs-Id)
• Header: Authorization: Bearer ocost_sk_…

Die Werkzeuge auflisten:

curl -sS https://api.ocost.io/public/mcp \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Beispiel: eine Odoo-Entwicklerin

Eine Odoo-Entwicklerin schreibt das Modul aus Odoo anbinden und fragt mit einem Schlüssel mit search:read und documents:read in Claude Code:

Entwicklerin: Finde die Rechnung von Büromöbel Schmidt über die Bürostühle und zeig mir, welche Felder von account.move und seinen Zeilen jeder Wert füllt.

Assistent ruft find_company auf (name: "Büromöbel Schmidt"), dann search_documents (query: "Bürostuhl", company_id: …, kinds: ["invoice"]), findet Rechnung BS-7790, ruft get_document auf und antwortet: seller.vat_id findet den partner_id, number ist die ref, issue_date das invoice_date, due_date das invoice_date_due; jede der beiden lines wird ein Eintrag in invoice_line_ids mit quantity, price als price_unit und vat_rate, das die Vorsteuer findet; totals.gross, 3946.04, prüft Odoos Summe.

Entwicklerin: Gibt es seit Januar Gutschriften von ihnen?

Assistent ruft find_documents auf (kind: "credit_note", company_id: …): keine seit Januar.