mcpees

OAuth-geschützte MCP-Server auf Cloudflare Workers — plus die Übersichtsseite, die sie auflistet.

Der Vorgänger auf Vercel (hero-mcp.vercel.app) ist am 06.08.2026 abgeschaltet worden und antwortet auf jeden Aufruf mit HTTP 410 samt Verweis auf den neuen Endpoint. Aus der Übersicht ist er entfernt; der 410-Stub bleibt für alle, die noch die alte URL eingetragen haben.

Was hier drin ist

shared/           OAuth-Server, MCP-Protokoll, Gestaltung — von allen Servern benutzt
servers/hero/     HERO-Handwerkersoftware, 34 Tools
servers/sevdesk/  sevdesk-Buchhaltung, 21 Tools
hub/              Übersichtsseite: alle Server, alle Tools, live vom Server geholt
scripts/          Build, Schema-Validierung, Tests, Deployment

Ein neuer Server besteht aus drei Dingen: Tools schreiben, Zugangsdaten prüfen, Kontext bauen. OAuth, MCP-Protokoll, Anmeldeseite und Routing kommen aus shared — siehe shared/src/types.ts für den Vertrag und servers/sevdesk/src/index.ts als Beispiel.

Related MCP server: MCP OAuth Test

HERO MCP

Ein Model-Context-Protocol-Server für HERO. 17 lesende und 17 schreibende Tools. Bearbeiten und Löschen gibt es bewusst nicht — kein Tool kann bestehende Daten überschreiben.

Mehrmandantenfähig. Der Server hat keinen HERO-Key. Beim Verbinden öffnet sich eine Anmeldeseite, auf der jeder Nutzer seinen eigenen HERO-API-Key hinterlegt. Der Key wird gegen HERO geprüft und dann verschlüsselt in KV abgelegt — mit einem Schlüssel, der aus dem ausgestellten OAuth-Token abgeleitet ist. Wer nur die KV-Daten hat, sieht Chiffretext.

Die mandantenspezifischen IDs (Projekttyp, Pipeline-Stufen, Dokumenttypen, Terminkategorien, Maßnahmen, die eigene partner_id) werden pro Zugang aus HERO abgeleitet und 12 Stunden zwischengespeichert. Nichts davon steht im Code.

OAuth

Vollständiger Authorization Server im Worker, ohne Fremdbibliothek:

• RFC 8414 Authorization Server Metadata, RFC 9728 Protected Resource Metadata

• RFC 7591 Dynamic Client Registration (Claude registriert sich selbst)

• RFC 7636 PKCE mit S256 — Pflicht, nicht optional

• Refresh-Token-Rotation, Einmal-Auth-Codes, RFC 7009 Revocation

sevdesk MCP

21 Tools für sevdesk: Kontakte, Ausgangsrechnungen, Eingangsbelege, Angebote und Aufträge, Artikel, Bankkonten und Umsätze, Umsatzauswertung, offene Posten, erlaubte Buchungskonten, PDF-Links. Angelegt werden Kontakte, Artikel, Rechnungsentwürfe, Eingangsbelege und Belegdateien.

Nicht enthalten sind Ändern und Löschen — und darüber hinaus alles, was den Zustand eines bestehenden Belegs verschiebt: buchen, versenden, stornieren, zurücksetzen, festschreiben. Festschreiben ist bei sevdesk laut eigener Doku aus rechtlichen Gründen unwiderruflich; so etwas gehört nicht in einen Chatverlauf.

Auth ist ein eigener API-Token pro Nutzer: 32 Hexzeichen aus Einstellungen → Benutzer. Der Token hängt am Benutzer und erbt dessen Rechte — wer nur lesen lassen will, legt in sevdesk einen Benutzer mit Leserechten an und nimmt dessen Token.

Vier Eigenheiten prägen die Umsetzung:

• Unbekannte Filter werden ignoriert, nicht abgelehnt. Ein Tippfehler in einem Query-Parameter kostet bei sevdesk keine Fehlermeldung, sondern die Filterwirkung: die Antwort kommt ungefiltert zurück und sieht völlig richtig aus. Deshalb prüft der Client jeden Aufruf gegen die eingefrorene API-Beschreibung, bevor er rausgeht — Pfad, Methode, Parametername und erlaubte Werte.

• Filter auf Fremdobjekte brauchen zwei Parameter. contact[id]=17 allein filtert nichts; ohne contact[objectName]=Contact liefert sevdesk die ganze Liste. Dieselbe Falle, dieselbe Wirkung. refQuery() setzt grundsätzlich beide.

• Datumsfilter sind Zeitstempel. Bei Rechnungen, Belegen und Aufträgen heißen sie startDate/endDate und wollen Unix-Sekunden. Ein durchgereichtes YYYY-MM-DD ergibt keine Fehlermeldung, sondern eine unbrauchbare Liste.

• taxRule oder taxType, je nach Konto. Mit dem sevdesk-Update 2.0 hat taxRule das alte taxType abgelöst. Welche Welt gilt, sagt /Tools/bookkeepingSystemVersion; der Server fragt das ab und schickt die passende Angabe. Die falsche bedeutet 422 — oder einen Beleg mit falscher Steuerregel.

Dazu eine Lücke, die man nicht wegdiskutieren kann: sevdesk verlangt beim Anlegen contactPerson (ein SevUser), unity (eine Einheit) und addressCountry (ein Land), hat aber für keines dieser drei Objekte einen Endpunkt zum Nachschlagen. Es gibt kein /SevUser, kein /Unity, kein /StaticCountry. Statt undokumentierte Pfade zu raten, liest servers/sevdesk/src/defaults.ts die IDs mit embed aus dem neuesten vorhandenen Beleg des Kontos und legt sie 12 Stunden ab — wie bei HERO die Mandanten-IDs. In einem frischen Konto ohne jeden Beleg fehlt die Grundlage; dann sagt der Server das, statt eine ID zu erfinden.

Die eingefrorene API-Beschreibung (servers/sevdesk/schema/sevdesk-api.json, 151 Operationen) stammt aus der offiziellen OpenAPI-Datei im Repo nikolausm/mcp-sevdesk (MIT, © Michael Nikolaus), auf Pfade, Methoden und Parameter eingedampft. Dessen Server ist ein stdio-Prozess mit generiertem Client und Tools zum Ändern, Buchen und Löschen; hier ist es ein remote erreichbarer Worker mit OAuth 2.1, und geschrieben wird ausschließlich Neues.

Vorher stand an dieser Stelle ein Server für Lexware Office (17 Tools). Er ist am 10.08.2026 abgelöst und samt Worker und KV-Namensraum gelöscht worden. Ein FLOWWER-Server (Rechnungsfreigabe) lag hier ebenfalls und ist am selben Tag entfernt worden. Was von FLOWWER bleibt: Brand.fields nimmt seither eine Liste von Eingabefeldern statt eines einzelnen.

Korrektheit ohne Live-Zugang

Die HERO-API meldet bei mehreren Operationen Erfolg und verwirft dabei still Daten. Der Skill hero-api dokumentiert diese Fallen; sie sind hier eingebaut statt kommentiert: Mutations laufen ausnahmslos über GraphQL-Variablen, Schreibvorgänge werden zurückgelesen, Artikel bekommen zwingend sales_prices + default_sales_price (sonst kalkuliert HERO mit dem Einkaufspreis), Checklisten-Einträge werden nach dem Anlegen nachgezählt.

Zwei Prüfungen laufen bei jedem Build, weil ohne HERO-Key kein Tool ausführbar ist:

npm run validate   # jede GraphQL-Operation gegen HEROs Introspection-Schema
npm run typecheck

scripts/validate-queries.mjs parst die 42 Operationen im Quelltext und prüft jedes Feld und jedes Argument gegen servers/hero/schema/hero-schema.json. Zusätzlich prüft der Client zur Laufzeit die Feldnamen jedes Input-Objekts gegen eine generierte Karte (scripts/gen-input-fields.mjs) — ein productId statt product_id fliegt auf, bevor ein Request rausgeht.

npm test fährt beide Server gegen Attrappen von KV und Fremdsystem:

• 19 Prüfungen HERO — kompletter OAuth-Flow: Code-Tausch, PKCE, Einmalgebrauch des Codes, Refresh-Rotation, Widerruf, ein echter tools/call, und dass weder Key noch Token im Klartext in KV landen.

• 76 Prüfungen sevdesk — dazu die Rechenlogik (Umsatz gestellt/bezahlt, offene Posten mit Teilzahlung, Überfälligkeit), die vier Fallen von oben, die Paginierung über mehrere Seiten, der Download-Link samt base64-Dekodierung, das Zurücklesen nach dem Anlegen und ein zweites Konto, das keinerlei Belege hat.

Zwei Dinge daran sind mehr als Zierde. Erstens prüft eine Zusicherung, dass jedes Tool mindestens einmal wirklich läuft — weil der Client jeden Aufruf gegen die API-Beschreibung prüft, fliegt ein falsch geschriebener Pfad oder Parameter damit im Test auf und nicht beim Nutzer. Zweitens hat genau diese Prüfung beim ersten Lauf einen echten Fund gemacht: /ContactAddress hat in der offiziellen Beschreibung überhaupt keine Query-Parameter, der Filter nach Kontakt ist also nirgends dokumentiert. Er ist jetzt einzeln freigegeben — und get_contact prüft zusätzlich selbst nach, ob jede zurückgegebene Adresse wirklich zu dem Kontakt gehört.

Ein früherer Ratenbegrenzungs-Test hat einen anderen echten Fehler gefunden: die Drossel lag am Client-Objekt und startete bei jedem Tool-Aufruf neu, sodass zwei Tools nacheinander ihre Requests im Abstand von 4 ms abgefeuert hätten. Sie liegt seither auf Modulebene, pro Token.

Bauen und deployen

npm install
npm run build     # generiert, validiert, typisiert, bündelt alle Worker
npm test          # kompletter OAuth-Flow gegen den Bundle, mit KV- und HERO-Attrappe

export CLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=…
node scripts/deploy.mjs servers/hero/wrangler.jsonc servers/hero/dist/worker.js
node scripts/deploy.mjs hub/wrangler.jsonc hub/dist/worker.js

Die Bindings liest das Deploy-Skript aus wrangler.jsonc, weil die Cloudflare-API bei jedem Upload alle Bindings ersetzt — ein vergessenes Flag löscht sonst still ein Binding. Mit installiertem Wrangler geht auch npx wrangler deploy --config servers/hero/wrangler.jsonc.

Logos

shared/src/marks.ts hält die offiziellen Herstellerzeichen — unverändert, in den Originalfarben, direkt von den Anbietern:

Vorher standen dort Nachbauten. Das ist die schlechteste Variante: es sieht aus wie die Marke, ist aber keine. Entweder das echte Zeichen oder ein neutrales.

Neben dem SVG liegt jede Marke gerastert als PNG und ICO in shared/src/icons.generated.ts und wird unter /favicon.ico, /icon.png und /apple-touch-icon.png ausgeliefert. Das SVG allein reicht nicht: Connector-Listen, Lesezeichen und Startbildschirme holen sich eine dieser Dateien und zeigen sonst gar nichts. Erzeugt mit npm run gen:icons — das braucht einmalig Playwright, weil die Herstellerzeichen echte Pfade sind und kein Pixelraster. Das Ergebnis ist eingecheckt, der normale Build kommt ohne aus.

composeLogo() setzt ein Zeichen mittig auf eine abgerundete Fläche — dasselbe Bild dient als Favicon und als Kachel. HERO steht auf seinem Gelb, sevdesk weiß auf seinem Rot (#FB523B) — so, wie die Anbieter es selbst zeigen. Bei sevdesk sind Ausschnitt und Größe aus der Originaldatei abgemessen, damit die Kachel dieselben Proportionen hat wie das App-Icon; dafür beachtet composeLogo() jetzt auch einen viewBox-Ursprung ungleich null.

Die Logos kennzeichnen das angebundene System, mehr nicht. Der Fuß jeder Seite sagt, dass es fremde Marken sind und dass dies keine offiziellen Integrationen der Anbieter sind.

Gestaltung

Ein Stylesheet für alles: shared/src/style.ts. Viel Weiß, wenige Farben, harte Kontraste bei der Schrift, Haarlinien statt Schatten. Die Akzentfarbe gehört dem jeweiligen System (HERO gelb, sevdesk rot) und kommt nur in kleinen Flächen vor — die Seiten selbst bleiben schwarzweiß.

Bewegung gibt es nur dort, wo sie etwas bedeutet: Inhalt tritt beim Laden gestaffelt ein, Karten heben sich beim Überfahren, der Kopierknopf quittiert. Nichts blinkt, nichts bewegt sich von allein weiter, und prefers-reduced-motion schaltet alles ab.

Die Übersichtsseite erklärt zuerst, was ein MCP überhaupt ist — sie richtet sich an Kollegen, die den Begriff zum ersten Mal lesen, nicht an Entwickler.

Einen Server aufnehmen

hub/src/registry.ts um einen Eintrag ergänzen und in hub/wrangler.jsonc das passende Service-Binding eintragen. Die Tool-Liste wird nicht in der Registry gepflegt, sondern zur Laufzeit vom Server geholt (/tools.json oder tools/list), damit die Übersicht nicht auseinanderläuft.

Der Server muss nicht aus diesem Repo kommen — Tarifcheck und Mikdaten liegen in eigenen Repos und werden nur eingetragen. Bei Mikdaten steckt der MCP-Server sogar im Worker der Anwendung selbst, nicht in einem eigenen Dienst; für den Hub macht das keinen Unterschied. Nötig ist von ihm nur ein /tools.json im bekannten Format; auth und mcpUrl darin sind optional, der Hub nutzt sie nicht.

Trägt ein Server nur lesende oder nur schreibende Tools, fällt der jeweils leere Abschnitt auf der Detailseite weg, und die Übersicht schreibt „nur lesend" statt „6 lesend, 0 schreibend". Der Markenhinweis im Fuß nennt die Anbieter, die in der Registry als thirdPartyBrand markiert sind — eigene Dienste stehen dort nicht.