SVEAG API & MCP Server: Dokumentation

SVEAG ist ein Gebäudedienstleister für Wohnimmobilien. Alles, was die Website anbietet – Angebotsanfrage, Ausschreibung über SVEAG Vergabe, Bewerbung auf offene Stellen, Informationen zu Leistungen und Standorten – können KI-Agenten auch maschinell erledigen: über die HTTP-API v1, über zwei MCP-Server, über WebMCP im Browser, über NLWeb und A2A. Es gibt keine Anmeldung und keinen API-Schlüssel (https://sveag.de/auth.md). Zum Ausprobieren gibt es eine Sandbox, die nichts sendet.

Schnellstart: SVEAG API v1

Basis-URL: https://sveag.de/api/v1. Lesen: GET /company, /services, /locations, /jobs, /search?q=, /pricing. Senden: POST /inquiries (Angebotsanfrage), /tenders (Ausschreibung), /applications (Bewerbung). Vollständige Beschreibung: https://sveag.de/openapi.json.

curl -s 'https://sveag.de/api/v1/search?q=winterdienst+leipzig&limit=3'

curl -s https://sveag.de/api/v1/inquiries \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1c9e1e-0b5a-4f7e-9a51-1d2b3c4d5e6f' \
  -d '{"name":"Max Muster","email":"max@example.de","postalCode":"20149","city":"Hamburg","serviceTypes":["winter_service"],"message":"Winterdienst für ein Mehrfamilienhaus, 12 Einheiten."}'

Sandbox (Testumgebung)

https://sveag.de/api/sandbox/v1 hat dieselben Endpunkte wie Produktion. POST-Einsendungen werden dort vollständig geprüft, aber nicht gesendet: Antwort HTTP 200 mit sandbox true und referenceNumber SANDBOX-0000, bei Fehlern dieselben 422-Antworten wie in Produktion. So lässt sich eine Integration testen, ohne dass bei SVEAG eine Anfrage ankommt.

curl -s https://sveag.de/api/sandbox/v1/inquiries \
  -H 'Content-Type: application/json' \
  -d '{"name":"Test","email":"test@example.de","postalCode":"20149","city":"Hamburg","message":"Test"}'

Listen und Pagination

Listen-Endpunkte sind cursorbasiert: Antwort {"data":[…],"pagination":{"limit":20,"next_cursor":"MjA","has_more":true,"total":180}}. Für die nächste Seite ?cursor=<next_cursor> anhängen; zusätzlich steht der Link im Header Link mit rel="next". limit geht von 1 bis 100.

Fehler, Limits, Wiederholungen

Fehler kommen als application/problem+json (RFC 9457) mit type, title, status, code und detail; bei 422 zusätzlich errors je Feldname. Codes: invalid_json, invalid_query, validation_failed, unknown_job, not_found, method_not_allowed, rate_limited, upstream_error, internal_error.

Rate Limits je IP: 120 lesende und 10 schreibende Anfragen pro Minute. Jede Antwort trägt RateLimit und RateLimit-Policy; bei Überschreitung HTTP 429 mit Retry-After.

Idempotency-Key: Einen eindeutigen Wert (z. B. UUID) bei POST mitsenden. Wiederholungen mit demselben Schlüssel liefern 24 Stunden lang dieselbe Antwort (Header Idempotent-Replayed: true) und senden nicht doppelt.

Versionierung

Die Hauptversion steht im Pfad (/api/v1) und im Header API-Version. Innerhalb von v1 gibt es nur abwärtskompatible Erweiterungen (neue Felder, neue Endpunkte). Eine Abkündigung wird mindestens sechs Monate vorher mit den Headern Deprecation und Sunset und auf dieser Seite angekündigt.

MCP-Server

Produkt-Server: https://sveag.de/mcp (Streamable HTTP, JSON-RPC 2.0, zustandslos, ohne Authentifizierung). Werkzeuge: get_company_info, list_services, search_site, list_jobs, send_inquiry, start_tender, apply_for_job, jeweils mit inputSchema, outputSchema und Annotationen (readOnlyHint, destructiveHint). Ressourcen: llms.txt, pricing.md, Entwicklerdoku, OpenAPI, Fakten.

Doku-Server: https://sveag.de/docs/mcp mit search_docs und fetch_page, um Fragen aus den Seiten von sveag.de zu beantworten.

Server-Karte: https://sveag.de/.well-known/mcp/server-card.json.

curl -s https://sveag.de/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

In Claude, ChatGPT oder Cursor einbinden

Als Remote-MCP-Server mit der URL https://sveag.de/mcp hinzufügen (und optional https://sveag.de/docs/mcp). Für Clients mit Konfigurationsdatei:

{
  "mcpServers": {
    "sveag": { "type": "http", "url": "https://sveag.de/mcp" },
    "sveag-docs": { "type": "http", "url": "https://sveag.de/docs/mcp" }
  }
}

WebMCP im Browser

Auf jeder Seite von sveag.de registriert die Website dieselben Werkzeuge per document.modelContext.registerTool(). Die Definitionen stehen als Literale im HTML; Agenten im Browser können sie direkt aufrufen, ohne Formulare auszufüllen.

NLWeb und A2A

NLWeb v0.55: POST https://sveag.de/ask mit {"query":{"text":"Winterdienst Leipzig"}} liefert Treffer als JSON; mit {"prefer":{"streaming":true}} als Server-Sent Events (start, result, complete).

A2A: Agent-Karte unter https://sveag.de/.well-known/agent-card.json, JSON-RPC-Endpunkt https://sveag.de/a2a (Methode SendMessage).

Discovery-Dateien

llms.txt (Überblick, mit Bereichsdateien /leistungen/llms.txt, /standorte/llms.txt und /docs/llms.txt) und llms-full.txt (Volltext), /.well-known/ard.json (Agent Resource Catalog), /.well-known/api-catalog (RFC 9727), /.well-known/agent-skills/index.json (Agent Skills v0.2.0), /pricing.md, /auth.md, /openapi.json und /sitemap.xml. Jede Seite gibt es zusätzlich als Markdown: Pfad plus .md, etwa https://sveag.de/leistungen/winterdienst.md, oder per Accept: text/markdown.

Regeln für Agenten

Lesende Endpunkte und Werkzeuge sind frei. Anfragen, Ausschreibungen und Bewerbungen nur mit ausdrücklicher Zustimmung der Person senden, in deren Namen sie gehen, und nur mit ihren echten Angaben; zum Testen die Sandbox nutzen. Fragen: kontakt@sveag.de.