API
Obolus stellt eine schlanke öffentliche API für Payroll- und Tax-Compare-Workflows bereit. MCP und OpenAPI beschreiben denselben freigegebenen Tool-Scope.
Die Developer API ist bewusst schlank gehalten und deckt derzeit Payroll- und Tax-Compare-Workflows ab. Der Scope wird kontrolliert erweitert und befindet sich aktuell im Early Public Status.
Für allgemeine MCP-Clients steht /api/mcp/public bereit; /api/mcp/claude bleibt als kompatibler Alias. Die ChatGPT-App verwendet /api/mcp. Die JSON-Beschreibung des Tool-Scopes liegt unter /api/mcp-discovery.
OpenAPI ist die REST-orientierte Spezifikation derselben öffentlichen Tools. Verwende /api/openapi für Swagger-kompatible Dokumentation, Client-Generierung und formale Request/Response-Schemas.
Der aktuelle Public Scope umfasst Discovery über MCP und OpenAPI sowie die beiden Tools berechne und taxcompare. Cockpit-, Budget- und Invest-Interaktionen bleiben bewusst Produkt-Flow und werden nicht als Public API veröffentlicht.
Obolus publishes a Model Context Protocol (MCP) server for tax calculation, a Claude-compatible MCP endpoint, and an OpenAPI specification so AI agents, developer tools, and LLM crawlers can discover the public payroll and tax comparison API surface.
Swagger-compatible OpenAPI specification for the Obolus REST API, including payroll and tax comparison schemas.
Machine-readable descriptor for the public Obolus Model Context Protocol tool scope.
Remote Model Context Protocol (MCP) server for tax calculation, net salary workflows, and country tax comparison agents.
Agent-neutral read-only Model Context Protocol endpoint for Obolus payroll and tax comparison tools.
Claude-compatible tool-only Model Context Protocol endpoint for Obolus payroll and tax comparison tools.
AI-system orientation file listing canonical Obolus pages and machine-readable API resources.
Die Obolus ChatGPT App nutzt dieselbe öffentliche MCP- und API-Oberfläche für globale Netto- und Gehaltsvergleiche. Sie ist eine technische Integration des Obolus-Rechenkerns, kein separater Consumer-Flow.
Für die meisten öffentlichen Integrationen ist REST über OpenAPI plus direkter Tool-Call die richtige Wahl. MCP ist die bessere Schicht für Agenten, Tool-Runtime-Systeme und Clients, die Discovery und Invocation über einen Gateway-Ansatz brauchen.
Empfohlen für klassische Integrationen, Dashboards, Backend-Services, SDK-Generierung und konventionelle API-Clients.
Empfohlen für AI-Agents, Tool-Runner und Systeme, die Tool-Discovery und Invocation über eine kompakte, maschinenlesbare Beschreibung verwenden wollen.
Die öffentlichen, nur lesenden Rechentools sind ohne Anmeldung und API-Key nutzbar. Ein API-Key ist für Integrationen optional; einzelne Deployments können ihn für bestimmte Endpunkte voraussetzen. Bevorzugter Header ist x-public-api-key.
Die API nutzt Contract-Versionen statt /v1-URLs. API-Contract: 2.1.0; MCP-Tool-Contract: 1.0.1. Unterstützte MCP-Protokollgenerationen umfassen 2025-11-25, 2026-07-28. Contract- und Protokollversion sind unterschiedliche Angaben.
Die API selbst ist sprachneutral und lebt unter /api/..., nicht unter einem Locale-Präfix. Die /de-, /en- und /tr-Pfade gelten für die Dokumentation, nicht für die API-Endpunkte.
REST-Limits: taxcompare 20 requests / 5 minutes; berechne 60 requests / 5 minutes für Cache-Misses. MCP-Transport: POST 200 requests / 5 minutes, GET 100 requests / 5 minutes; beide MCP-Endpunkte haben getrennte Kontingente. Zusätzliche Limits je MCP-Tool oder verifiziertem API-Key werden nur bei entsprechender Serverkonfiguration aktiviert. Cache-Hits bei berechne können vor der REST-Limit-Prüfung beantwortet werden.
Für Suchmaschinen und die erste Orientierung reicht die Kurzfassung: dieselben Tool-Verträge decken alle unterstützten Länder ab, aber die Bedeutung einzelner Payroll-Felder unterscheidet sich je nach Steuersystem.
OpenAPI-Spezifikation (Swagger-kompatibel)
JSON-Discovery für Tool-Scope, Metadaten und Docs
Streamable HTTP MCP-Transport für ChatGPT und andere MCP-Clients
Öffentliche MCP-Rechentools für alle Clients
Bisheriger MCP-Pfad ohne ChatGPT-UI-Metadaten
/api/berechneDirekter Payroll- und Tax-Call
/api/taxcompareDirekter Salary-Compare-Call
REST-Erfolgsantworten liefern tool-spezifische Strukturen ohne globales ok/data-Envelope. MCP-Antworten enthalten zusätzlich eine Zusammenfassung mit Beträgen in Haupteinheiten sowie, soweit vorhanden, Berechnungszeit, Daten- und Methodenstand, Annahmen, Warnungen und die vom Backend gelieferte engine_revision. Ergebnisse können sich bei geändertem Steuerdatenstand oder Wechselkurs trotz gleicher Eingaben ändern. REST-Fehler enthalten error sowie gegebenenfalls details oder restricted_fields.
Beispielantwort (taxcompare, gekürzt):
{
"results": [
{
"country": "DE",
"net": 39750,
"tax": 13000,
"social_contributions": 7250,
"effective_rate": 33.75,
"input_annual_gross": 60000,
"input_currency": "eur",
"comparison_basis": "shared_gross"
}
]
}Typische Fehlercodes:
{
"error": "Invalid taxcompare payload.",
"details": [
"body.countries must contain at least 1 items."
]
}curl -s https://www.obolusfinanz.de/api/openapicurl -s https://www.obolusfinanz.de/api/mcp-discoverycurl -N -H "Accept: text/event-stream" https://www.obolusfinanz.de/api/mcpcurl -X POST https://www.obolusfinanz.de/api/taxcompare \
-H "Content-Type: application/json" \
-d '{
"salary_ct": 6000000,
"tax_year": "2026",
"countries": ["DE", "AT", "AU"],
"currency": "eur",
"gross_mode": "shared_gross"
}'curl -X POST https://www.obolusfinanz.de/api/taxcompare \
-H "Content-Type: application/json" \
-d '{
"tax_year": "2026",
"countries": ["DE", "CH", "UK"],
"currency": "eur",
"gross_mode": "local_median_gross"
}'curl -X POST https://www.obolusfinanz.de/api/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "taxcompare",
"arguments": {
"salary_ct": 6000000,
"tax_year": "2026",
"countries": ["DE", "AT", "AU"],
"currency": "eur",
"gross_mode": "shared_gross"
}
}
}'MCP und OpenAPI werden aus derselben Vertragsquelle erzeugt. Diese Contract-Quelle ist die verbindliche Grundlage der öffentlichen API. Änderungen am Backend sollten immer gemeinsam mit dem öffentlichen Contract ausgeliefert werden.
Die Obolus API ist bewusst einfach, offen und für reale Finanz-Tools gedacht.
Wenn du die API in einem öffentlich sichtbaren Produkt nutzt, freuen wir uns über einen kleinen Hinweis:
Die API entwickelt sich aktiv weiter. Kern-Endpunkte bleiben stabil, während Response-Strukturen sich im Detail verbessern können. Für produktive Integrationen empfehlen wir, Responses defensiv zu verarbeiten.
Bei Fragen zur öffentlichen API, für API-Key-Anfragen, manuelle Freischaltung oder für höheren Durchsatz nutze bitte das Kontakt- oder Feedback-Formular auf der Website, um API-Keys zu erhalten oder Limits anzupassen.