MCP-Server für KI-Agenten

Der MCP-Server unter https://mcp.quellenkontor.dev/v1 ist ein entfernter Server nach dem Model Context Protocol. Er spricht Streamable HTTP: Jede Anfrage ist ein JSON-RPC-Aufruf per POST, die Antwort kommt als JSON. Er hält keine Sitzungen, jede Anfrage steht für sich.

• Für jeden Datensatz gibt es ein Werkzeug, benannt nach dem Muster hr_datensatz.
• Alle Werkzeuge lesen nur. Sie sind als lesend, nicht verändernd und wiederholbar gekennzeichnet, viele Clients rufen sie deshalb ohne Rückfrage auf.
• Jedes Ergebnis beginnt mit einem fertigen Satz zum Zitieren, danach folgen die Daten als Text und als strukturiertes Objekt mit denselben Feldern wie die REST-API.
• Der Server gibt dem Agenten Regeln mit: Werte nachschlagen statt schätzen, fehlende Angaben erfragen, Rechtsgrundlage und Quelle zitieren. Derselbe Text steht als Prompt quellenkontor_regeln bereit und unten zum Kopieren.

Du brauchst einen Schlüssel aus dem Konto. Er wird als Header Authorization: Bearer qk_live_… mitgeschickt.

Claude Code

Mit einem Befehl im Terminal:

$ claude mcp add --transport http quellenkontor \
    https://mcp.quellenkontor.dev/v1 \
    --header "Authorization: Bearer $QK_KEY"

Oder als Datei .mcp.json im Projekt. Claude Code setzt ${QK_KEY} aus deiner Umgebung ein, der Schlüssel steht also nicht in der Datei:

{
  "mcpServers": {
    "quellenkontor": {
      "type": "http",
      "url": "https://mcp.quellenkontor.dev/v1",
      "headers": {
        "Authorization": "Bearer ${QK_KEY}"
      }
    }
  }
}

Cursor

In ~/.cursor/mcp.json. Die Datei liegt in deinem Home-Verzeichnis, nicht im Projekt. Trag deinen Schlüssel direkt ein und leg die Datei nie in ein Repository:

{
  "mcpServers": {
    "quellenkontor": {
      "url": "https://mcp.quellenkontor.dev/v1",
      "headers": {
        "Authorization": "Bearer qk_live_DEIN_SCHLUESSEL"
      }
    }
  }
}

VS Code

In .vscode/mcp.json. VS Code fragt den Schlüssel beim ersten Start ab und speichert ihn sicher:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "quellenkontor-key",
      "description": "Quellenkontor-API-Schlüssel",
      "password": true
    }
  ],
  "servers": {
    "quellenkontor": {
      "type": "http",
      "url": "https://mcp.quellenkontor.dev/v1",
      "headers": {
        "Authorization": "Bearer ${input:quellenkontor-key}"
      }
    }
  }
}

Claude Desktop

Claude Desktop bindet entfernte Server mit festem Header über die Brücke mcp-remote ein, die per npx startet (Node.js nötig). In der Konfigurationsdatei von Claude Desktop:

{
  "mcpServers": {
    "quellenkontor": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.quellenkontor.dev/v1",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer qk_live_DEIN_SCHLUESSEL"
      }
    }
  }
}

Der Header steht ohne Leerzeichen nach dem Doppelpunkt, den Schlüssel liest mcp-remote aus der Variable AUTH_HEADER. Die Datei liegt auf deinem Rechner, leg sie nie in ein Repository.

Andere Clients

Getestet haben wir Claude Code, Cursor und VS Code. Jeder andere Client, der entfernte Server über Streamable HTTP mit eigenem Header anbinden kann, funktioniert mit diesen beiden Angaben: Adresse https://mcp.quellenkontor.dev/v1 und Header Authorization mit deinem Schlüssel.

Claude im Browser, Claude Desktop, die Claude-Apps und ChatGPT binden entfernte MCP-Server als Connector ein. Statt eines Schlüssels im Header nutzen sie OAuth: Du erlaubst den Zugriff einmal im Browser, danach fragt die Anwendung mit einem eigenen Schlüssel für dein Konto ab. Einen Schlüssel aus dem Konto brauchst du dafür nicht.

Claude

1. Öffne in Claude die Connectors und füge einen eigenen Connector (Custom Connector) hinzu.
2. Trag als Adresse https://mcp.quellenkontor.dev/v1 ein. Client-ID und Client-Secret bleiben leer, Claude registriert sich selbst.
3. Fragt der Dialog nach der Art der Anmeldung, wähle die Anmeldung per OAuth und nicht den Zugang ohne Anmeldung.
4. Klick auf Verbinden. Es öffnet sich quellenkontor.dev: Melde dich an, prüf Anwendung, Weiterleitung und Konto und klick auf Erlauben.

Der Connector gilt danach in Claude im Browser, in Claude Desktop und in den Apps. In Team- und Enterprise-Organisationen legt ihn eine Person mit Adminrechten an, jedes Mitglied verbindet danach sein eigenes Konto.

ChatGPT

1. Schalte in ChatGPT in den Einstellungen unter Apps den Entwicklermodus ein und leg eine eigene App mit MCP-Server an.
2. Trag als Adresse https://mcp.quellenkontor.dev/v1 ein und wähle als Authentifizierung OAuth. ChatGPT registriert sich selbst, Client-ID und Secret brauchst du nicht.
3. ChatGPT öffnet danach quellenkontor.dev. Melde dich an und klick auf Erlauben.

Was bei der Anmeldung passiert

• Die Zustimmungsseite zeigt den Namen der Anwendung, die Adresse, an die Quellenkontor dich zurückschickt, dein Konto und deinen Tarif. Den Namen gibt die Anwendung selbst an, verlass dich auf die Adresse.
• Mit Erlauben legt Quellenkontor einen API-Schlüssel mit dem Namen „MCP: Name der Anwendung“ an und übergibt ihn der Anwendung. Er steht im Konto bei deinen anderen Schlüsseln und zählt zur Höchstzahl deines Tarifs.
• Werkzeugaufrufe über den Connector verbrauchen dasselbe Kontingent wie jede andere Abfrage. initialize und tools/list gehen auch ohne Anmeldung, erst ein Werkzeugaufruf braucht den Schlüssel.
• Der Schlüssel läuft nicht ab. Sperrst du ihn im Konto, antwortet der Server auf den nächsten Werkzeugaufruf mit 401. Claude fragt dann neu nach der Anmeldung, in ChatGPT verbindest du die App neu.
• Jede Verbindung legt einen eigenen Schlüssel an. Verbindest du eine Anwendung neu, sperr den alten Schlüssel im Konto, sonst ist die Höchstzahl schnell erreicht.

Technische Angaben

Das vollständige Eingabeschema jedes Werkzeugs steht in der Referenz des Datensatzes unter "Schema für MCP". Ein Agent bekommt es über tools/list.

Ein Bot für ein Thema braucht selten alle 24 Werkzeuge. Mit einem Zusatz an der Adresse liefert tools/list nur einen Teil, das spart Tokens und verhindert Verwechslungen:

Die Bereiche heißen lohn (Löhne und Grenzen), sozialversicherung (Sozialversicherung und Abgaben), steuer (Steuer und Reisekosten), fristen (Arbeitsrecht und Fristen), kalender (Kalender).

Viele Chatbot-Frameworks reichen die Regeln des Servers nicht an das Modell weiter. Dann kopierst du sie in den Systemprompt deiner Anwendung:

Quellenkontor liefert amtliche HR-Werte und gesetzliche Berechnungen nur für Deutschland, Tabellen ab 2015 (Mindestausbildungsvergütung ab Ausbildungsbeginn 2020), Feiertage und Arbeitstage von 2015 bis 2035. Für Österreich, die Schweiz oder andere Länder gelten sie nicht. Rufe ein Werkzeug auf, sobald eine Antwort einen dieser Werte braucht, auch wenn du ihn zu kennen glaubst. Rechne relative Angaben wie „nächstes Jahr“ oder „ab Juli“ in ein Datum im Format JJJJ-MM-TT um und nenne es in der Antwort. Fehlen Angaben, von denen das Ergebnis abhängt, etwa Anschaffungsdatum, Geburtsdatum oder Jahrgang, Ausbildungsbeginn oder Bundesland, frag nach, statt sie zu raten. Fragt jemand nach einem ganzen Jahr, prüfe unterjährige Änderungen mit hr_verlauf und den Parametern von und bis. Übernimm das zitat, wenn es die Frage beantwortet, und nenne immer die Quelle mit URL. Geht es um einen einzelnen Bestandteil, etwa Aufmerksamkeiten oder den Pflegemindestlohn für Fachkräfte, frag mit dem Parameter bestandteil ab oder nimm Wert, gueltig_ab, rechtsgrundlage und quelle dieses Eintrags aus bestandteile. Steht vorlaeufig: true in der Antwort, sag, dass der Wert für diesen Stichtag noch nicht amtlich festgelegt ist. Meldet ein Werkzeug kein_wert, ist der Wert noch nicht verkündet: Sag das, statt zu schätzen. Gib warnungen und einschränkende hinweise weiter. Steuerfreie Höchstsätze begründen keinen Anspruch, und ein geldwerter Vorteil ist nicht die Steuer. Die Rechner wenden die gesetzliche Regel schematisch an und ersetzen keine Rechtsberatung.

So sieht ein Werkzeugaufruf auf dem Draht aus. Normalerweise erledigt das dein Client, zum Testen geht es auch mit curl:

curl -X POST https://mcp.quellenkontor.dev/v1 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $QK_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hr_mindestlohn","arguments":{"datum":"2027-01-15"}}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Gesetzlicher Mindestlohn in Deutschland am 15.01.2027: 14,60 Euro brutto je Stunde, gültig ab 01.01.2027. Minijob-Grenze: 633 Euro im Monat. Rechtsgrundlage: Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025, Stufe 2. Quelle: Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025 (BGBl. 2025 I Nr. 268), https://www.recht.bund.de/bgbl/1/2025/268/VO.html. Daten: Quellenkontor (quellenkontor.dev)."
      },
      {
        "type": "text",
        "text": "(dieselben Daten wie structuredContent, als kompaktes JSON)"
      }
    ],
    "structuredContent": {
      "datensatz": "mindestlohn",
      "datum": "2027-01-15",
      "mindestlohn_brutto_stunde": 14.6,
      "minijob_grenze_monat": 633,
      "gueltig_ab": "2027-01-01",
      "gueltig_bis": null,
      "rechtsgrundlage": "Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025 (BGBl. 2025 I Nr. 268), Stufe 2",
      "quelle": {
        "titel": "Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025 (BGBl. 2025 I Nr. 268)",
        "url": "https://www.recht.bund.de/bgbl/1/2025/268/VO.html"
      },
      "minijob_rechtsgrundlage": "§ 8 Abs. 1a SGB IV (Mindestlohn × 130 ÷ 3, aufgerundet auf volle Euro)",
      "minijob_quelle": {
        "titel": "Bekanntmachung der Geringfügigkeitsgrenze nach § 8 Absatz 1a SGB IV vom 7. November 2025 (BAnz AT 20.11.2025 B1)",
        "url": "https://www.bundesanzeiger.de/pub/publication/VaPRG6wPGXte9CM3jI4/content/VaPRG6wPGXte9CM3jI4/BAnz%20AT%2020.11.2025%20B1.pdf"
      },
      "vorheriger_wert": {
        "gueltig_ab": "2026-01-01",
        "mindestlohn_brutto_stunde": 13.9,
        "minijob_grenze_monat": 603
      },
      "naechster_wert": null,
      "hinweise": [
        "Die Minijob-Grenze gilt je Monat. Gelegentliches unvorhersehbares Überschreiten ist in engen Grenzen erlaubt (§ 8 Abs. 1b SGB IV).",
        "Die Pauschalabgaben des Arbeitgebers für Minijobs (Kranken- und Rentenversicherung, Pauschsteuer, Umlagen) liefert der Datensatz minijob-abgaben (/v1/hr/minijob-abgaben)."
      ],
      "lizenz": "Werte aus amtlichen Werken (§ 5 UrhG). Nutzung der Zusammenstellung nach den Nutzungsbedingungen von Quellenkontor.",
      "stand": "2026-09-23",
      "zitat": "Gesetzlicher Mindestlohn in Deutschland am 15.01.2027: 14,60 Euro brutto je Stunde, gültig ab 01.01.2027. Minijob-Grenze: 633 Euro im Monat. Rechtsgrundlage: Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025, Stufe 2. Quelle: Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025 (BGBl. 2025 I Nr. 268), https://www.recht.bund.de/bgbl/1/2025/268/VO.html. Daten: Quellenkontor (quellenkontor.dev).",
      "datenstand": "2026-09-23.1"
    },
    "isError": false,
    "_meta": {
      "quellenkontor.dev/kontingent": {
        "limit": 1000,
        "verbraucht": 12,
        "tarif": "kostenlos"
      }
    }
  }
}

Ein Werkzeugaufruf mit Ergebnis zählt wie eine Abfrage der REST-API. Frei sind initialize, tools/list und Aufrufe mit fehlerhaften Argumenten. Den Stand nach jedem Aufruf findest du im Ergebnis unter _meta im Schlüssel quellenkontor.dev/kontingent, mit Limit, Verbrauch und Tarif.

• Unterstützte Protokollversionen: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Der Server antwortet mit der Version, die der Client anfragt, sonst mit der neuesten.
• Methoden: initialize, ping, tools/list, tools/call, prompts/list und prompts/get (Prompt quellenkontor_regeln). resources/list liefert eine leere Liste.
• Kein Stream vom Server: GET auf die Adresse beantwortet der Server mit 405, Benachrichtigungen ohne id mit 202.
• Keine Sitzungen: Der Header Mcp-Session-Id wird nicht gebraucht.

Der MCP Inspector ist das offizielle Testwerkzeug des Protokolls. Er zeigt alle Werkzeuge mit Schema und lässt dich Aufrufe von Hand ausführen:

npx @modelcontextprotocol/inspector

Im Inspector wählst du den Transport Streamable HTTP, trägst die Adresse https://mcp.quellenkontor.dev/v1 ein und setzt unter Authentication den Header Authorization mit Bearer qk_live_….

Ein guter Agent nennt in der Antwort die Rechtsgrundlage und die Quelle aus dem Ergebnis, fragt nach fehlenden Angaben und sagt, wenn ein Wert noch vorläufig ist. Wenn deine Anwendung eigene Anweisungen an das Modell gibt, schreib hinein, dass HR-Werte nur aus den Werkzeugen kommen dürfen.