JSON-API

Utilico stellt seine Rechner und seine Einheiten-Umrechnung als offene JSON-API bereit: kein Schlüssel, keine Anmeldung, kein Rate-Limit-Vertrag. Gerechnet wird mit exakt derselben Funktion wie in den Tools selbst – dieselben Faktoren wie auf den 326 Umrechnungsseiten, dieselbe Formel wie im Formular.

Endpunkte

Basis-URL ist https://utilico.de. Alle Endpunkte sind lesend, beantworten GET und erlauben Cross-Origin-Zugriff (Access-Control-Allow-Origin: *).

GET /api/rechner/<slug>

Ruft einen Rechner auf und liefert sein Ergebnis als JSON. Die Parameter sind dieselben, die auch die Tool-Seite in der Adresse führt: /tool/bmi?groesse=180&gewicht=75 und /api/rechner/bmi?groesse=180&gewicht=75 rechnen dasselbe, nur an verschiedenen Orten. Welche Felder ein Rechner kennt, steht im Katalog unten, in seiner Markdown-Fassung (/tool/bmi.md) und für alle zusammen in /openapi.json.

Anfrage

curl "https://utilico.de/api/rechner/bmi?groesse=180&gewicht=75"

Antwort

{
  "rechner": {
    "slug": "bmi",
    "name": "BMI-Rechner",
    "beschreibung": "Berechne deinen Body-Mass-Index aus Größe und Gewicht – inklusive Einordnung.",
    "kategorie": "rechnen",
    "kategorieName": "Rechnen",
    "seite": "https://utilico.de/tool/bmi",
    "markdown": "https://utilico.de/tool/bmi.md"
  },
  "eingaben": {
    "gewicht": 75,
    "groesse": 180
  },
  "standardwerte": {},
  "parameter": [
    {
      "name": "gewicht",
      "label": "Gewicht (kg)",
      "typ": "number",
      "min": 0.1,
      "step": 0.1,
      "standard": 75
    },
    {
      "name": "groesse",
      "label": "Größe (cm)",
      "typ": "number",
      "min": 0.1,
      "step": 0.1,
      "standard": 178
    }
  ],
  "hinweise": [],
  "ergebnis": {
    "art": "text",
    "bezeichnung": "BMI",
    "wert": "23,1"
  },
  "ergebnisse": [
    {
      "art": "text",
      "bezeichnung": "BMI",
      "wert": "23,1"
    },
    {
      "art": "text",
      "bezeichnung": "Einordnung",
      "wert": "Normalgewicht"
    },
    {
      "art": "note",
      "wert": "Der BMI ist ein grober Richtwert und berücksichtigt z.B. Muskelmasse oder Alter nicht."
    }
  ],
  "text": "BMI: 23,1\nEinordnung: Normalgewicht\nHinweis: Der BMI ist ein grober Richtwert und berücksichtigt z.B. Muskelmasse oder Alter nicht.",
  "berechnung": {
    "ort": "server",
    "hinweis": "Diese Antwort hat ein Server berechnet. Auf https://utilico.de/tool/bmi rechnet der Browser – dort bleiben die Eingaben auf dem Gerät."
  },
  "dokumentation": "https://utilico.de/api",
  "beschreibung": "https://utilico.de/openapi.json",
  "katalog": "https://utilico.de/api/rechner",
  "beispiel": "https://utilico.de/api/rechner/bmi?gewicht=82&groesse=178"
}

ergebnisse enthält jeden Block, den der Rechner erzeugt hat, mit seiner Art:text, note und warnung tragen ihren Wortlaut,image und file sagen nur, dass etwas entstanden ist – die Datei selbst liegt auf der Seite und nicht in der Antwort.

ergebnis ist keine Zusammenfassung, sondern eine Wiederholung: derselbe Block noch einmal, den die Seite groß herausstellt – und wo sie keinen herausstellt, der erste. Dieselbe Form zweimal, damit niemand zwei Formen auspacken muss, um an die Antwort zu kommen. Wo das Ergebnis seiner Natur nach kein einzelner Wert ist – ein Kalender, eine Tabelle –, fehlt das Feld ganz; einen Wert zu erfinden, damit das Feld dasteht, wäre schlechter als seine Abwesenheit.text ist das ganze Ergebnis als Fließtext, eine Zeile je Block und Hinweis: beziehungsweise Warnung: davor, wo es sonst wie ein Zwischenergebnis aussähe – das Feld für alle, die nur Platz für eine Antwort haben.

eingaben nennt die Werte, mit denen tatsächlich gerechnet wurde, und hinweise alles, was die API dabei zurechtgerückt hat. Beides steht in jeder Antwort, auch in der fehlerhaften. Der Maßstab dafür ist das Formular: Die API weist ab, was das Formular abweist, und rückt zurecht, was es zurechtrückt. Abgewiesen wird also ein unbekannter Parameter, ein unbekannter Auswahlwert, eine Zahl, die keine ist – und eine Zahl außerhalb der Grenzen eines Zahlenfeldes; die Antwort nennt dann unter erlaubt die Spanne. Zurechtgerückt wird der Schieberegler, und nur er: Er hat keine Stelle, an der ein Wert außerhalb stünde, weshalb /tool/qr?groesse=600 im Browser wie hier 512 bedeutet. Deshalb kommt eine Antwort nie stillschweigend anders zustande, als man sie bestellt hat:

curl "https://utilico.de/api/rechner/farbverlauf?winkel=540"

{
  "eingaben": {
    "c1": "#2f6df6",
    "c2": "#16b981",
    "typ": "linear",
    "winkel": 360
  },
  "hinweise": [
    "„winkel=540“ liegt über dem Maximum – auf 360 gesetzt."
  ]
}

Nicht jeder Rechner antwortet hier. 120 der 146 tun es; die übrigen26 liefern 422 mit einem Grund und der Adresse, unter der es doch geht. Das ist kein Ausbau-Rückstand, sondern in den meisten Fällen der Sinn der Sache: passwort und die anderen Rechner der Kategorie Sicherheit erzeugen Passwörter, und ein Server, der ein Passwort erzeugt, hat es erst einmal gehabt. Die übrigen Gründe sind technisch – ein Rechner braucht eine hochgeladene Datei, ein <canvas> oder gar kein Formular. Welcher Grund für welchen Rechner gilt, steht im Katalog.

GET /api/rechner

Listet alle 146 Rechner mit ihren Feldern auf – die Bezugsquelle für gültige Parameternamen und Auswahlwerte. Jeder Eintrag trägt berechenbar; wo das false ist, stehen daneben grund und eine Meldung im Klartext. Mit ?kategorie=gesundheit lässt sich die Antwort auf eine Kategorie einschränken.

curl "https://utilico.de/api/rechner?kategorie=gesundheit"

Auch die gesperrten Rechner stehen in dieser Liste. Ein Verzeichnis, das sie verschweigt, ließe einen Agenten glauben, es gäbe hier keinen Passwort-Generator – dabei gibt es ihn, nur eben nicht über HTTP.

GET /api/umrechnen

Rechnet einen Wert von einer Einheit in eine andere um. Beide Einheiten müssen zur selben Familie gehören.

Anfrage

curl "https://utilico.de/api/umrechnen?von=km&nach=meile&wert=42"

Antwort

{
  "familie": {
    "id": "laenge",
    "name": "Länge",
    "art": "linear"
  },
  "von": {
    "code": "km",
    "name": "Kilometer",
    "symbol": "km"
  },
  "nach": {
    "code": "meile",
    "name": "Meile",
    "symbol": "mi"
  },
  "wert": 42,
  "ergebnis": 26.097590074,
  "formatiert": "26,09759 mi",
  "faktor": 0.621371192237,
  "formel": "mi = km × 0,621371192237",
  "seite": "https://utilico.de/umrechnen/km-in-meile",
  "rechner": "https://utilico.de/tool/laenge"
}

ergebnis ist der Wert zum Weiterrechnen, auf 12 signifikante Stellen gerundet – genauer als jeder Umrechnungsfaktor selbst, aber frei von Fließkomma-Artefakten wie 98.60000000000001. formatiert ist die anzeigefertige deutsche Schreibweise.faktor ist bei Temperaturen null, weil dort ein Offset dazukommt – die Rechenvorschrift steht dann in formel.

GET /api/einheiten

Listet alle Familien mit ihren Einheiten auf – die Bezugsquelle für gültige Werte von von und nach. Mit ?familie=laenge lässt sich die Antwort auf eine Familie einschränken.

curl "https://utilico.de/api/einheiten?familie=laenge"

Familien und Einheiten

Umgerechnet wird immer innerhalb einer Familie. Ein Aufruf mit von=kg&nach=km ergibt daher einen Fehler.

Fehler

Fehler tragen ein maschinenlesbares Feld fehler, dazu eine Klartext-Meldung und Links zur Doku. Beim Umrechnen kommen sie mit Status 400; mögliche Codes sind parameter_fehlt, unbekannte_einheit, unpassende_einheiten,ungueltiger_wert und unbekannte_familie.

{
  "fehler": "unpassende_einheiten",
  "meldung": "Kilogramm (Gewicht) lässt sich nicht in Kilometer (Länge) umrechnen.",
  ...
}

Bei den Rechnern hängt der Status davon ab, wem der Fehler gehört: 400, wenn die Anfrage etwas Unmögliches verlangt, 404 für einen Slug, den es nicht gibt, 422 für einen Rechner, den es gibt, der aber über HTTP nicht rechnet, und 500, wenn wir es sind. Die Codes:

• unbekannter_rechner, unbekannte_kategorie, unbekannter_parameter, ungueltiger_wert, eingabe_ungueltig, kein_ergebnis, rechenfehler – etwas an der Anfrage stimmt nicht oder die Rechnung ging schief
• nur_im_browser, nur_auf_dem_geraet, kein_formular, datei_noetig, geheimes_feld – der Rechner antwortet hier grundsätzlich nicht; die Meldung nennt die Seite, auf der es geht
• methode_nicht_erlaubt – alles außer GET, HEAD und OPTIONS

Maschinenlesbare Beschreibung

Die API ist nach RFC 8288 und RFC 9727 auffindbar: Jede Seite dieser Website trägt einen Link-Header, der auf den API-Katalog und die OpenAPI-Beschreibung zeigt.

• /openapi.json – OpenAPI 3.1, mit allen Einheiten-Codes als Enum und einem eigenen Pfad je Rechner: Felder, Grenzen und die erlaubten Werte jeder Auswahlliste stehen dort, damit ein Agent sie nicht 146 Mal einzeln erfragen muss
• /.well-known/api-catalog – API-Katalog als Linkset (RFC 9727)
• /llms.txt – Kurzüberblick der ganzen Website für Sprachmodelle

MCP-Server

Wer einen Agenten baut, der das Model Context Protocol spricht, muss die Endpunkte oben nicht selbst verdrahten: unter https://utilico.de/mcp läuft ein MCP-Server über Streamable HTTP – ohne Anmeldung, ohne Schlüssel. Trag die Adresse in deinem MCP-Client ein, dann stehen dort 6 Werkzeuge bereit:

• werkzeug_finden – sucht unter allen 146 Rechnern nach einem Stichwort und nennt Kurzname, Beschreibung und Adresse der Treffer. Der Einstieg, wenn noch nicht feststeht, welcher Rechner passt – ohne den ganzen Bestand zu lesen
• einheiten_auflisten – alle Familien mit ihren gültigen Codes
• einheiten_umrechnen – rechnet um, mit Faktor, Formel und Belegseite
• seite_als_markdown – holt eine Seite dieser Website als Markdown
• rechner_oeffnen – öffnet einen der 146 Rechner, wahlweise mit vorbelegten Feldern, und nennt die Felder, die er kennt
• rechner_rechnen – führt einen der 120 serverseitig rechenbaren Rechner aus und gibt sein Ergebnis zurück, dazu die Feldliste für den nächsten, genaueren Aufruf

Die beiden letzten sehen sich ähnlich und sind es nicht: Das eine liefert eine Zahl, das andere den Rechner. Welches passt, entscheidet sich an den Daten und nicht an der Bequemlichkeit, denn nur rechner_rechnen schickt sie über das Netz – bei einer Kreditrate belanglos, bei einem Gehalt nicht. Die 26 Rechner, die oben gesperrt sind, stehen in seiner Auswahl deshalb erst gar nicht; wer es dennoch versucht, bekommt gesagt, warum – und den Weg zu rechner_oeffnen, wo derselbe Rechner im Gerät des Nutzers läuft.

Die Antworten sind dieselben JSON-Körper wie oben – Server und API stehen im Quelltext auf derselben Funktion, sie können also nicht auseinanderlaufen. Ausgehandelt werden die Protokollversionen 2025-11-25, 2025-06-18, 2025-03-26; welche das sind und wo der Endpunkt liegt, steht auch in der Server Card.

Werkzeuge ruft das Modell selbst auf, wenn es rechnen will. Zwei weitere Dinge wählt dagegen der Mensch: Ressourcen hängt er dem Gespräch als Kontext an, noch bevor er etwas fragt. Drei feste gibt es, dazu eine Vorlage für alles andere:

• /llms.txt – Alle Rechner im Überblick
• /api/einheiten – Einheiten und ihre Codes
• /openapi.json – OpenAPI-Beschreibung der JSON-API
• /{+pfad} – Beliebige Seite als Markdown, also etwa /tool/bmi oder /umrechnen/km-in-meile

Prompts startet er aus einer Liste – in vielen Clients ein Schrägstrich-Befehl. Jeder legt eine der Fertigkeiten ins Gespräch, die unter /.well-known/agent-skills/ ohnehin veröffentlicht sind, und hängt die eigene Aufgabe daran: fertigkeit_einheiten_umrechnen, fertigkeit_rechner_per_webmcp, fertigkeit_seiten_als_markdown, fertigkeit_tool_links_vorbelegen. Der Text kommt beim Aufruf aus der jeweiligen SKILL.md – es ist dieselbe Datei, die auch ein Agent liest, der die Website von außen durchsucht, und damit keine zweite Fassung derselben Anleitung.

Von Hand ist es ein POST mit JSON-RPC 2.0. Ein GET auf den Endpunkt beantwortet der Server absichtlich mit 405 und einem kurzen Wegweiser – dieser Server hält keine offene Verbindung, jeder Aufruf steht für sich.

curl -X POST https://utilico.de/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"einheiten_umrechnen","arguments":{"von":"km","nach":"meile","wert":42}}}'

Ein Rechner im Chatfenster

Ein Werkzeug fällt aus der Reihe: rechner_oeffnen antwortet nicht nur mit Text, es bringt eine Oberfläche mit. Clients, die die Erweiterung io.modelcontextprotocol/ui beherrschen, finden sie als Ressource ui://utilico/rechner vom Typ text/html;profile=mcp-app und zeigen sie neben der Antwort an. Darin steht der aufgerufene Rechner selbst – dieselbe Seite /embed/<kurzname>, die auch fremde Websites einbetten, ohne zweite Fassung und ohne eigenen Nachbau.

Der Umweg über ein Fenster im Fenster hat einen Grund: Darin rechnet der Browser des Nutzers, nicht unser Server. Ein Gehalt, ein Körperfettanteil oder der Inhalt einer PDF-Datei verlässt das Gerät also auch dann nicht, wenn der Rechner mitten im Gespräch steht – der Client stellt nur den Rahmen, gerechnet wird darin. Was dabei herauskommt, meldet die Oberfläche als Text zurück ins Gespräch (ui/update-model-context), das Modell muss es also nicht vom Bildschirm abschreiben. Clients ohne diese Erweiterung verlieren nichts: Sie bekommen wie bisher den vorausgefüllten Link und die Liste der Felder, die der Rechner kennt.

Für die 26 gesperrten Rechner ist das nicht nur der schonendere, sondern der einzige Weg. Bei den übrigen 120 steht er neben rechner_rechnen zur Wahl – und ist ihm überall dort vorzuziehen, wo die Werte den Nutzer etwas angehen.

WebMCP – die Rechner im Browser

Der MCP-Server oben rechnet die Einheiten-Umrechnung und 120 der 146 Rechner selbst; für die übrigen reicht er ein Fenster durch, in dem sie laufen, und für alle bietet er es an. Wer als Agent ohnehin schon in einem Browser sitzt, braucht weder das eine noch das andere – über WebMCP meldet jede Seite ihre Werkzeuge direkt beim Browser an, und der Agent ruft sie dort auf. Auf der Seite selbst rechnet dann derselbe Code, der auch das Fenster füllt: im Gerät, ohne Netz, ohne Wartezeit.

Auf jeder Seite stehen 4 Werkzeuge bereit: werkzeug_finden, einheiten_auflisten, einheiten_umrechnen und seite_als_markdown. Alle stehen im MCP-Server oben ebenfalls, mit denselben Namen, Schemata und Antwortkörpern – sie stammen aus derselben Quelle, ein Agent bekommt also je nach Weg keine zweite Wahrheit vorgesetzt. Was hier fehlt, sind die 2 Rechner-Werkzeuge, und beide aus demselben Grund: rechner_oeffnen öffnet einen Rechner in einem Fenster, und dieser Agent steht schon davor; rechner_rechnen schickte die Werte an unseren Server, während der Rechner daneben dieselbe Zahl im Gerät ausrechnet.

Zusammen ergibt das den Weg, der ohne Seitenwechsel auskommt: werkzeug_finden nennt die Adresse eines Rechners, seite_als_markdown nennt dessen Eingabefelder, und erst dann lohnt es sich, die Seite zu öffnen – wo der Rechner selbst als Werkzeug wartet.

Auf einer Tool-Seite kommt der Rechner dieser Seite dazu, benannt nach ihrem Pfad (/tool/bmi → bmi). Sein Eingabeschema wird aus den Feldern des Formulars abgeleitet, mitsamt Grenzen, Vorgaben, Einheiten und den erlaubten Auswahlwerten – es ist keine zweite, von Hand gepflegte Beschreibung und kann deshalb nicht vom Formular abweichen. Derzeit sind 127 der 146 Rechner so anmeldbar; nicht dabei sind die Tools mit Dateieingabe (ein Agent kann keine Datei beisteuern) und die rein interaktiven wie Stoppuhr oder Zeichenfläche, die kein Ergebnis zurückgeben.

Ein Aufruf bedient dabei das echte Formular: Danach stehen die Werte in den Feldern, das Ergebnis im Ergebnisbereich und der Zustand in der Adresszeile. Der Mensch am Bildschirm sieht also, was der Agent getan hat, und bekommt in der Antwort den Link, der genau dorthin zurückführt. Alle Werkzeuge sind mit readOnlyHint markiert – es wird gerechnet, nichts gespeichert und nichts versendet.

Browser, die WebMCP nicht kennen, laden den zugehörigen Code gar nicht erst: Die Seite prüft die Schnittstelle und holt das Modul nur dann nach. Für alle anderen Besucher kostet WebMCP damit nichts.

Seiten als Markdown

Nicht alles steckt in der API: Erklärtexte, Formeln und Umrechnungstabellen stehen auf den Seiten selbst. Damit ein Agent sie nicht erst aus dem HTML schälen muss, liefert jede Seite auf Wunsch eine Markdown-Fassung – ohne Navigation, Werbeflächen und Skripte.

curl -H "Accept: text/markdown" https://utilico.de/umrechnen/km-in-meile

Dieselbe Fassung gibt es unter einer festen Adresse, indem du .md an den Pfad hängst – etwa /umrechnen/km-in-meile.md. Die Antwort trägt Content-Type: text/markdown und in x-markdown-tokens eine Schätzung ihrer Tokenzahl, damit sich der Abruf vorab budgetieren lässt. Ohne den Accept-Header bleibt es bei HTML, Browser merken davon also nichts.

Die Textfassung wird beim Build aus genau der Seite abgeleitet, die auch der Browser bekommt. Sie ist keine zweite, separat gepflegte Fassung und kann deshalb nicht veralten.

Nutzung

Die API ist kostenlos und darf auch kommerziell genutzt werden. Es gibt kein hartes Limit, aber eine Bitte: Antworten sind 24 Stunden cachebar (Cache-Control: max-age=86400), weil Umrechnungen deterministisch sind – bitte nicht dieselbe Umrechnung im Sekundentakt erneut abrufen. Für die Ergebnisse gilt die Haftungsregelung aus dem Impressum: sorgfältig gepflegt, aber ohne Gewähr. Bei Fragen oder wenn du die API in großem Umfang einsetzen möchtest, schreib gern an [email protected].