---

tags:

• api
• contract
• agent
• mcp date: 2026-04-16 project: "work7" api_version: "json-rpc-2.0" status: draft

API: mcp-overview

Ort: work7_laendletech/docs/api/api-mcp-overview.md

Überblick

• Base-URL / Prefix: /mcp
• Auth: X-API-Key oder optional Bearer, plus verpflichtende Work7-Kontext-Header
• Format: JSON-RPC 2.0
• Source of truth: C:\Users\ngrei\Projects\mcp\src\central-mcp-server

Endpoint(s)

POST /mcp

Zweck:

Zentraler MCP-Endpunkt fuer Tool-Discovery und Tool-Aufrufe. Das ist die agent-first Vertragsflaeche des Projekts und wird vom agent-service als Remote MCP konsumiert. Der externe Server ist central-mcp-server und registriert sowohl Work7-Tools als auch zentrale Kalender-Tools.

Request

Feld	Typ	Pflicht	Beschreibung
jsonrpc	string	ja	Muss 2.0 sein
id	string	ja	Request-ID
method	string	ja	tools/list oder tools/call
params.name	string	bei tools/call ja	Tool-Name, z. B. customers.list
params.arguments	object	bei tools/call nein	Tool-Argumente

Response 200

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "success": true,
          "data": {}
        }
      }
    ]
  }
}

Fehler

HTTP	Bedeutung	Body-Hinweis
400	JSON-RPC oder Tool-Request ungueltig	error
401	Auth fehlt/ungueltig	error
403	Firmen-/Rollenkontext ungueltig	error
500	Tool- oder Serverfehler	error

Request Context Headers

Header	Pflicht	Beschreibung
Content-Type: application/json	ja	JSON-RPC Payload
Accept: application/json	ja	Antwortformat
X-API-Key	meist ja	Auth fuer zentralen MCP
X-Work7-User-Id	ja	User-Kontext
X-Work7-User-Role	ja	Rollen-Kontext 1, 2, 3
X-Work7-Company-Id	ja	Firmenkontext
X-Work7-Language	nein	Sprachkontext
X-Work7-Channel	nein	Kanal, z. B. web, whatsapp, api
X-Work7-Session-Id	nein	Sessionkontext
X-Work7-Caller	nein	Aufrufer, z. B. agent-service

Tool-Domains

Work7 contract v1

• work7.meta
• customers.*
• projects.*
• rapports.*
• offers.*
• invoices.*
• whatsapp_sessions.*

Additional central MCP domains

• calendar.* und weitere zentrale Tools werden im central-mcp-server ebenfalls registriert, gehoeren aber nicht zum eingefrorenen Work7-Contract-v1-Scope.

Rate Limiting / Limits

• Max Requests: Nicht explizit dokumentiert; haengt von MCP-Server und vorgelagerten Limits ab
• Timeout: agent-service nutzt standardmaessig 15s Remote-Timeout
• Max Payload: JSON-RPC Payload mit moderaten Argumentobjekten

Breaking Changes / Versionierung

• Der externe Work7-Contract ist auf toolsVersion: 1.0.0 eingefroren.
• Namespace-Namen und Tool-Namen sind der eigentliche Vertragskern.
• Multi-Word-Aktionen folgen snake_case.
• Neue Tools sind additiv.
• Umbenennungen von Tools oder Pflichtargumenten sind breaking.

Beispiel (curl)

curl -sS -X POST "{{mcp_base_url}}/mcp" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {{mcp_api_key}}" \
  -H "X-Work7-User-Id: 18" \
  -H "X-Work7-User-Role: 1" \
  -H "X-Work7-Company-Id: mueller-bau-de" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

Verwandte Notes

• Feature-Spec: work7
• OpenAPI/Schema: MCP JSON-RPC, kein klassisches REST-Schema
• Externer Vertrag: mcp/src/central-mcp-server/contracts/work7-tools.v1.md

Follow-ups

• Postman Collection prüfen: passt es in bestehende Collection? Sonst neu anlegen → work7_laendletech/src/postman/ 📅 2026-04-16
• In Feature-Spec verlinken falls zugehörig 📅 2026-04-16