Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VR-MCP.md
T

26 KiB

VR-MCP · MCP-Server (Read- + Action-Tools für externe KI-Clients)

Typ Dev (Code)
Owner Raffael
Phase v2-P4 — MCP (ersetzt „KI-Tiefe", AD-26)
Cycle/Fenster v2-W1 — Public-API/Postfach/Abo/KI-Start · Start 18.07. · fällig 2026-07-20
Status Done — 8/8 DoD = 100 % done; Staging-Proof gilt als Abschluss, Prod-Promote bewusst später

Entscheidung / Kontext (AD-26)

KI→MCP-Pivot: HiveGrid hostet kein eigenes LLM/RAG mehr. Statt KI-App wird HiveGrid KI-anschließbar über einen MCP-Server (Model Context Protocol). Externe KI-Clients (Claude Desktop/Cursor/ChatGPT) docken an, lesen HiveGrid-Daten und führen Aktions-Tools aus — die Inferenz liegt beim Client. Ersetzt VR-P25 (HiveMind/RAG, zurückgestellt). Baut auf der Public-API-Fläche (VR-P22a/VR-P22b) auf — keine Doppelarbeit.

Host-/Runtime-Contract (verbindlich)

  • MCP läuft ausschließlich auf mcp.hivegrid.de (staging: staging-mcp.hivegrid.de).
  • MCP läuft als eigener Coolify-Service/Container hivegrid-mcp mit eigener Runtime (apps/mcp), nicht im Web- oder Public-API-Container.
  • Public API bleibt auf api.hivegrid.de; MCP-Routen werden nicht unter app.hivegrid.de oder api.hivegrid.de bereitgestellt. Auth/Scopes/Rate-Limit werden aus VR-P22b wiederverwendet, aber die Host-/Runtime-Surface bleibt getrennt.
  • MCP nutzt den Host selbst als Connector-URL; es gibt keinen zusätzlichen /mcp-Pfad.

Was zu bauen ist

Remote MCP-Server, der die mandanten-gescopte HiveGrid-Daten-/Aktions-Fläche als MCP-Tools exponiert:

  • Transport: Streamable HTTP (stateless Start) auf https://mcp.hivegrid.de; SDK @modelcontextprotocol/sdk. Kein stdio, kein deprecated SSE.
  • Auth v1: OAuth 2.1 Authorization Code + PKCE für „Connect-in-Minutes" aus Claude/Cursor/ChatGPT. MCP ist Resource Server auf https://mcp.hivegrid.de; HiveGrid Web ist Authorization Server auf https://app.hivegrid.de. Pflicht: RFC 9728 Protected-Resource-Metadata, RFC 8414 Authorization-Server-Metadata, Resource-Indicator/Audience-Bindung, kurzlebige Access Tokens, rotierende Refresh Tokens, Consent + Widerruf. API-Key-Bearer bleibt nur als Operator-/Fallback-Pfad, nicht als primärer User-Connect-Flow.
  • Read-Tools: hg_lead_search/hg_lead_get, hg_contact_search, hg_project_get, hg_pipeline_list (readOnlyHint). (Tools statt Resources — breiterer Client-Support.)
  • Write-Tools: hg_lead_create, hg_project_set_stage, hg_activity_add — je mit withPermission() + Client-Confirmation + auditEvent/logActivity. Annotations (destructiveHint/idempotentHint) gesetzt.
  • Toolflächen-Nachzug 2026-07-12: zusätzlich hg_project_search, hg_contact_get, hg_activity_list, hg_task_search, hg_task_get, hg_task_create, hg_task_set_status. Damit umfasst der Vertrag 15 Tools. Für Activities und Tasks kommen die granularen OAuth-Scopes mcp:activity:read, mcp:task:read und mcp:task:write hinzu; die Bündel mcp:read/mcp:write bleiben kompatibel.
  • Tenant aus dem Token (NIE aus Tool-Argumenten) → withTenantScope() + RLS als zweite Mauer.
  • Security: Rate-Limit pro Tenant/Token, Output-Limits + Pagination, Zod-Input-Validierung (Fehler als isError:true), Origin- + Protocol-Version-Checks, kein Token-Passthrough, Tenant-Daten sind Daten, nie Instruktionen (Prompt-Injection-Härtung).

Benötigte Screens (Backend bedient — Design liefert VD-MCP)

Screen [Route] Kern-Inhalt
MCP-Verbindungen [Settings] OAuth-Connect-Flow je Client (Claude/ChatGPT/Cursor/VS Code/manuell), Consent + Scopes, aktive Verbindungen, Widerruf/Rotation, Setup-Hinweise, Audit der MCP-Tool-Aufrufe

Definition of Done

  • Remote-MCP-Server (Streamable HTTP) auf Staging erreichbar; eigener hivegrid-mcp Container; Session-Handling; Origin- + Protocol-Version-Checks
    • Code/Container/CI/Staging erledigt: apps/mcp, Docker-Target mcp, root-only Streamable HTTP, /mcp bewusst 404, Origin/Host-Allowlist via MCP_ALLOWED_*, Coolify-Ressource hivegrid-mcp, https://staging-mcp.hivegrid.de/healthz und /.well-known/oauth-protected-resource live. Entscheidung 2026-07-09: Staging-Proof reicht für Done; Prod-Promote auf mcp.hivegrid.de wird bewusst später gemacht und blockiert dieses Ticket nicht.
  • OAuth 2.1 v1-Auth: Protected-Resource-Metadata auf mcp.hivegrid.de, Authorization-Server-Metadata auf app.hivegrid.de, Authorization Code + PKCE, Token/Refresh/Revocation, DCR-fähiger Public-Client-Flow, Consent, Audience/Resource-Bindung, WWW-Authenticate Discovery
  • Fallback/Operator-Auth (API-Key-Bearer → Tenant/User/Scopes aus VR-P22b); 401+WWW-Authenticate
  • Read-Tools (Lead/Contact/Project/Pipeline) tenant-gescopt via withTenantScope() + RLS
  • Write-Tools mit withPermission() + Client-Confirmation + auditEvent + logActivity; Annotations gesetzt
  • Rate-Limit pro Tenant; Output-Limits + Pagination; Zod-Validierung; Prompt-Injection-Härtung; kein Token-Passthrough
  • Konnektor tenantHasModule('mcp'); RLS auf allen Tenant-Tabellen
  • E2E: echter Client per OAuth (Claude/Cursor/ChatGPT oder MCP Inspector) verbunden + je 1 Read-/Write-Tool ausgeführt — erfüllt 2026-07-03 mit Claude Code (s. Proof-Notizen unten)
    • Teilproof 2026-07-03: Dynamic Client Registration + Authorization Code + PKCE + Token Exchange auf Staging erfolgreich; offizieller MCP SDK Client verbindet gegen https://staging-mcp.hivegrid.de/ und listet 8 Tools. Offen: Read-/Write-Tool mit fachlichem Ergebnis; hg_pipeline_list scheiterte an fehlender Staging-DB-Tabelle public.Pipeline — aufgelöst 2026-07-03 (Akeshan, s. Notiz unten): Migration manuell per prisma migrate deploy nachgezogen, Tabelle vorhanden.
    • Funktionaler Voll-Proof 2026-07-03 abends (Akeshan, s. Notiz unten): kompletter OAuth-Flow (DCR mit Scopes + Browser-Consent + PKCE) + tools/list (8 Tools) + Read-Tool hg_pipeline_list (Sales-Pipeline mit 5 Stages) + Write-Tool hg_lead_create mit confirm=true (InboxLead angelegt) + AuditEvent (mcp.lead.create, sourceModule mcp, outcome success) + Activity (lead_created, „Lead per MCP erstellt.") in der Staging-DB verifiziert. Für den formalen Haken fehlt nur noch der Connect mit einem der benannten Produkt-Clients (Claude/Cursor/ChatGPT/MCP Inspector) — funktional ist nichts mehr offen.

Stand 2026-07-03: Scope-Update: MCP-Runtime/Tools/Deploy sind live und serverseitig verifiziert, aber OAuth 2.1 ist ab sofort v1-Pflicht und ersetzt den API-Key-Copy-Flow als primären User-Connect. Screens bleiben Folgearbeit aus VD-MCP; zuerst muss der OAuth-Flow funktional und per echtem Client testbar sein.

Technische Bausteine

  • @modelcontextprotocol/sdk (Server), StreamableHTTPServerTransport; eigener Service apps/mcp → hivegrid-mcp. Nicht in apps/web, apps/api oder RR7-Loader/Action quetschen.
  • Auth/Scopes/Rate-Limit aus VR-P22b wiederverwenden, aber als OAuth-Access-Token-Validierung kapseln; Tenant-Context-Middleware (Reihenfolge: TLS → Origin → Protocol-Version → OAuth Token + Audience/Resource → Tenant-Context → Rate-Limit → Zod → withPermission → Handler → Output-Truncation → Audit).
  • Querschnitt-Hülle: withTenantScope/withPermission (M004), auditEvent (M001), logActivity, notify (M011), Klartext-Fehler (M002) auch in Tool-isError-Texten.
  • Ausgangspunkt: vorhandenes apps/web/app/modules/mcp/ (mcp.server.ts / mcp-tools.server.ts / fetch-transport.server.ts). 2026-07-03 bereinigt: der alte Web-/mcp-Code wurde entfernt; MCP lebt jetzt ausschließlich in apps/mcp.

Umsetzungs-Notiz

2026-07-12 — Toolfläche von 8 auf 15 Tools erweitert (Follow-up, Ticket bleibt 8/8 DoD = 100 % done):

  • Neue Read-Tools: hg_project_search, hg_contact_get, hg_activity_list, hg_task_search, hg_task_get.
  • Neue bestätigungspflichtige Task-Writes: hg_task_create, hg_task_set_status; Status-No-op erzeugt keine doppelten Audit-/Activity-Einträge.
  • Backend-Prüfung und Umsetzung: Projekte berücksichtigen Owner/Projektleitung/Mitgliedschaft sowie explizite Pipeline-Denies und geben keine geschützten Geldfelder aus; Kontaktrelationen werden gegen die Sichtbarkeit des Gegenkontakts gefiltert; Activity-Metadaten/Related-Refs bleiben intern; Tasks nutzen Creator-/Assignee-/Watcher-/ Gruppen-Sichtbarkeit.
  • Task-Writes validieren Assignee, Gruppe und die fachliche Sichtbarkeit des Entity-Links tenant-lokal. Task, SearchIndexEntry, Search-Outbox, Audit-Outbox und Activity committen atomar in derselben RLS-Transaktion; konkurrierende Statuswechsel werden per Row-Lock serialisiert.
  • Output-Grenzen: Task-Suchen liefern keine vollständigen Beschreibungen/sourceRef; Task-Detailbeschreibungen und Watcher sowie Kontakt-Channels/-Relationen haben harte Caps mit Truncated-Markern. Activity-Metadaten bleiben intern, Summary-Texte werden begrenzt und als nicht vertrauenswürdige Daten markiert.
  • OAuth-/Resource-Metadata erweitert um mcp:activity:read, mcp:task:read, mcp:task:write; bestehende mcp:read-/mcp:write-Grants decken die neuen granularen Scopes weiterhin ab.
  • Kein Schema- oder Public-REST-Vertrag geändert. Auswirkung auf Abhängigkeiten ist in VR-P22b und auf den künftigen Scope-Screen in VD-MCP dokumentiert.
  • Lokaler Proof: pnpm --filter @hivegrid/mcp typecheck, build und test (43/43 Tests), fokussierter OAuth-Metadaten-Test (1/1), pnpm typecheck, pnpm lint, pnpm test (613 Test-Files / 3.788 Tests grün, 8 Files / 46 Tests bewusst skipped) sowie git diff --check. Separater Read-only-Endreview ohne verbleibende Critical-/High-/Medium-Findings.

2026-07-03: MCP als eigene Runtime umgesetzt:

  • Neues Workspace-Paket apps/mcp mit Streamable-HTTP-Server am Host-Root, McpServer + StreamableHTTPServerTransport, stateless JSON responses, DNS-Rebinding-Protection, Health/Ready-Endpunkten.
  • Tool-Fläche implementiert: hg_lead_search, hg_lead_get, hg_contact_search, hg_project_get, hg_pipeline_list, hg_lead_create, hg_project_set_stage, hg_activity_add.
  • Auth/Scopes/Rate-Limit umgesetzt: Bearer-API-Key, Tenant/User aus Key, WWW-Authenticate bei 401, MCP-Scope-Checks, Tenant/API-Key-Limits über Shared Store.
  • Sicherheits- und Cross-Cutting-Wiring umgesetzt: Tenant aus Token, Zod-Inputs, Cursor-Pagination, kompakte Outputs, confirm=true für Writes, withPermission, withTenantScope, auditEvent, logActivity, Prompt-Injection-Hinweise in Tool-Beschreibungen/Output.
  • Deploy/Runtime vorbereitet: Docker-Target mcp, verify:docker-mcp-runtime-smoke, Gitea-CI Job für MCP, Deploy-Workflow baut/pusht web/api/worker/mcp und deployt hivegrid-mcp als abhängige HTTP-Ressource.
  • Web-Altlast entfernt: apps/web/app/modules/mcp/** und apps/web/app/routes/mcp/** gelöscht; mcp/** bleibt nur als disabled/reserved route tree, nicht als aktive Web-Route.
  • Env/Doku aktualisiert: MCP_HOST, MCP_PORT, MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS, API_KEY_HASH_SECRET, Env-Katalog, Deployment-Doku.

2026-07-03 Scope-Entscheidung: OAuth 2.1 wird nicht mehr als spätere Stufe behandelt, sondern als v1-Funktionsscope. Begründung: Der gewünschte „Mit Claude/ChatGPT verbinden"-Flow braucht Discovery + Browser-Consent; statische API-Key-Config ist nur Fallback/Operator-Modus. Screens werden erst nach funktionalem OAuth-Proof finalisiert.

2026-07-03 OAuth-Implementierung: OAuth 2.1 serverseitig umgesetzt:

  • Neue Prisma-Modelle/Migration mcpOAuth.prisma + 20260703110500_vr_mcp_oauth: McpOAuthClient, McpOAuthAuthorizationCode, McpOAuthAccessToken, McpOAuthRefreshToken; Codes/Tokens nur hash-only.
  • Authorization Server im Web: /.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize, /oauth/authorize/approve, /oauth/token, /oauth/revoke.
  • MCP Resource Server: /.well-known/oauth-protected-resource, WWW-Authenticate mit Resource-Metadata, OAuth-Bearer- Validierung mit Audience/Resource-Bindung; API-Key bleibt Fallback/Operator-Pfad.
  • Staging/Prod-Config ergänzt: MCP_RESOURCE_URL, MCP_AUTHORIZATION_SERVER_URL, optional MCP_OAUTH_TOKEN_HASH_SECRET; Staging muss https://staging-mcp.hivegrid.de und https://staging-app.hivegrid.de setzen.

Aktueller Proof lokal (OAuth-Änderung):

  • pnpm --dir . exec prisma validate
  • pnpm --filter @hivegrid/db typecheck
  • pnpm --filter @hivegrid/db test -- --run src/api-keys.server.test.ts (Vitest-Wrapper lief paketweit: 57 Files, 437 Tests grün, 8 skipped)
  • pnpm --filter @hivegrid/web typecheck
  • pnpm --filter @hivegrid/mcp typecheck
  • pnpm --filter @hivegrid/mcp test

2026-07-03 Staging-/MCP-Client-Proof und aktueller Übergabestand:

  • Commits auf main:
    • 368533436 ci(deploy): stop exporting registry build cache — behebt Registry-Build-Cache-Export-Timeouts im CI.
    • 646f815b4 fix(mcp): expose oauth metadata route — /.well-known/oauth-authorization-server als echte Web-Route registriert.
    • fede041de fix(mcp): clarify missing bearer token error — 401-Text spricht korrekt von OAuth-Bearer-Access-Token.
    • 2663e019b / 6b97ebf96 — MCP-Transport-Lifecycle gefixt; Server bleibt bis zum HTTP-Response-Finish offen.
    • ee4c9a394 fix(db): add project pipeline core migration — fehlende P8-Projekt-/Pipeline-Core-Migration ergänzt.
  • Manuell verifiziert auf Staging:
    • https://staging-app.hivegrid.de/.well-known/oauth-authorization-server liefert 200 inkl. Authorization-/Token-/Registration-Endpunkten.
    • https://staging-mcp.hivegrid.de/.well-known/oauth-protected-resource liefert 200 inkl. Resource https://staging-mcp.hivegrid.de.
    • Unauthentifizierter MCP-Request liefert 401 mit WWW-Authenticate und resource_metadata.
    • Dynamic Client Registration (/oauth/register) + Browser-Authorize + PKCE-Code-Exchange (/oauth/token) funktionieren; Token-Werte wurden nicht dokumentiert.
    • Offizieller @modelcontextprotocol/sdk Client verbindet mit OAuth-Bearer-Token und listet Tools: hg_lead_search, hg_lead_get, hg_contact_search, hg_project_get, hg_pipeline_list, hg_lead_create, hg_project_set_stage, hg_activity_add.
  • Offen bei Übergabe an Akeshan:
    • Gitea-Deploy-Run 9168 für ee4c9a394 wurde grün; https://staging-app.hivegrid.de/healthz und https://staging-mcp.hivegrid.de/healthz zeigen beide Revision ee4c9a394032b66ad8e76895157a0c2527983a81.
    • Trotzdem scheitert hg_pipeline_list weiter mit The table public.Pipeline does not exist in the current database. Nächster Check: Hat Coolify die Web-Pre-Deployment-Migration wirklich ausgeführt, gegen welche DATABASE_URL/DIRECT_URL lief sie, und nutzt hivegrid-mcp dieselbe Staging-DB wie hivegrid-web?
    • Nach erfolgreichem Deploy/Migrate erneut testen:
      1. Mit dem bestehenden oder neuem OAuth-Token per MCP SDK client.listTools() prüfen.
      2. client.callTool({ name: "hg_pipeline_list", arguments: {} }) muss nach Migration nicht mehr mit public.Pipeline does not exist scheitern.
      3. Für vollständigen E2E danach ein Write-Tool mit confirm=true in einem geeigneten Test-Tenant ausführen und Audit/Activity prüfen.
  • Lokaler Proof für die Migration:
    • pnpm exec prisma validate --config prisma.config.ts
    • isolierter Postgres-16-Container: Migration 20260703123000_p8_project_pipeline_core/migration.sql mit psql -v ON_ERROR_STOP=1 erfolgreich angewendet; Tabellen Pipeline, PipelineStage, Projekt vorhanden.

2026-07-03 (Akeshan) — Staging-Migrations-Blocker aufgelöst (manuell nachgezogen):

  • Befund: prisma migrate status im Staging-Web-Container zeigte 20260703123000_p8_project_pipeline_core als einzige nicht angewandte Migration (166/167 applied), obwohl Deploy-Run 9168 grün war und Revision ee4c9a394 lief. Ursache = wie beim Befund in AK-P4a (2026-06-23): Coolify führt den per Deploy-Workflow gesetzten pre_deployment_command (prisma migrate deploy) nicht zuverlässig aus — die beiden früheren Migrationen vom selben Tag (07:01/09:33 UTC) kamen an, die von Run 9168 nicht. Der Deploy verifiziert auf Staging nur Health/Revision, keinen Migrations-Status → das Loch fällt erst beim ersten fachlichen Query auf.
  • Fix (bewusst nur manueller Trigger, Hook-Reparatur separat): pnpm exec prisma migrate deploy --config prisma.config.ts im Staging-Web-Container ausgeführt; Migration sauber angewandt (_prisma_migrations 14:25 UTC).
  • Verifiziert: migrate status → „Database schema is up to date" (167/167); SELECT count(*) auf Pipeline/PipelineStage/Projekt liefert 3/15/0 statt TableDoesNotExist. Raffaels DB-Frage geklärt: hivegrid-web und hivegrid-mcp nutzen dieselbe DB (DATABASE_URL = DIRECT_URL = selbe Postgres-Instanz, DB hivegrid) — kein URL-Mismatch.
  • Nächster Schritt E2E: client.callTool({ name: "hg_pipeline_list" }) erneut testen (sollte jetzt Daten liefern), danach Write-Tool mit confirm=true + Audit/Activity-Check.
  • ⚠️ Separater Befund (blockiert Teile des E2E, eigenes Follow-up nötig): Die Staging-DB hat darüber hinaus massiven Schema-Drift: prisma migrate diff (DB → Schema) zeigt 93 fehlende Tabellen, für die gar keine Migrations-Files existieren (AD-21-Muster: Feature-Branch db push, Merge-Migration nie erzeugt) — u.a. Kontakt, InboxLead, Dashboard, Auftrag-/Automation-/Kalender-/HR-/Forms-Domänen. Konsequenz hier: hg_contact_search/ hg_lead_search/hg_lead_create laufen auf Staging weiter in TableDoesNotExist, bis die fehlenden Merge-Migrationen erzeugt sind; sichtbares Symptom in der Web-App: 500 auf /demo-pro-crm/dashboard (prisma.dashboard.upsert → public.Dashboard fehlt). Der CI-Gate „migrate deploy gegen leere DB" (infra/LESSONS.md §9) fängt das nicht — er prüft nur vorhandene Migrations-Files, nicht Schema↔Migrations-Parität (dafür bräuchte es prisma migrate diff --from-migrations --to-schema --exit-code als Gate).

2026-07-03 abends (Akeshan) — Schema-Drift behoben + funktionaler E2E-Tool-Proof:

  • Drift-Befund von heute Mittag ist behoben: PR #32 (akeshan/schema-parity-catchup, gemerged als cf2d4d678) liefert die AD-21-Aufhol-Migration 20260703150000_ak_schema_parity_catchup (93 Tabellen/88 Enums, idempotent nach P8-Muster) plus den neuen CI-Gate verify:migrations-parity (Migrations-Replay in ephemeren Postgres, Diff gegen prisma/schema, verdrahtet im database-Job beider CI-Workflows) — „Schema geändert, Merge-Migration vergessen" bricht ab jetzt den PR statt erst Staging. Coolify-Hook hat die Migration beim Deploy erneut NICHT ausgeführt → manuell nachgezogen, migrate status 168/168 up to date, 262 Tabellen; /demo-pro-crm/dashboard und /contacts rendern (vom User im Browser bestätigt).
  • E2E-Tool-Proof gegen https://staging-mcp.hivegrid.de/ (standards-konformer OAuth-2.1-Client, Streamable HTTP):
    1. DCR /oauth/register — wichtig: scope muss im Registration-Request mitgegeben werden, sonst wird der Client nur mit Default-Scope registriert und /oauth/authorize lehnt mit „Scope not registered for this client" ab.
    2. Browser-Authorize + Consent (User-Session) + PKCE-S256-Code-Exchange → Access-Token mit allen 9 Scopes (1h).
    3. MCP-Requests brauchen einen erlaubten Origin-Header (MCP_ALLOWED_ORIGINS = https://staging-app.hivegrid.de, https://staging-web.hivegrid.de) — sonst 403 „Invalid Origin header".
    4. initialize + tools/list → 8 Tools; Read: hg_pipeline_list liefert die Sales-Pipeline mit 5 Stages (tenant-gescopt, Tenant demo-business-crm); Write: hg_lead_create mit confirm=true legt InboxLead cmr57zk0f000001mptutf1qf8 an (E2E Proof / vr-mcp-e2e-proof@example.test, status new, quelle custom).
    5. Querschnitt verifiziert in der Staging-DB: AuditEvent (action=mcp.lead.create, targetType=lead, sourceModule=mcp, outcome=success) + Activity (activityType=lead_created, actorKind=automation, „Lead per MCP erstellt.") — beide mit der Lead-Id als Target/Subject.
  • Rest für den formalen DoD-Haken: einmaliger Connect mit einem benanntem Produkt-Client (Claude/Cursor/ChatGPT/MCP Inspector) — funktional ist der Pfad komplett bewiesen. Danach Prod-Rollout (mcp.hivegrid.de) + VD-MCP-Screens.

2026-07-03 spät (Akeshan) — Produkt-Client-Connect (Claude Code) blockiert durch Origin-Check, Fix auf diesem Branch:

  • Befund: Claude Code als benannter Produkt-Client (claude mcp add --transport http hivegrid-staging https://staging-mcp.hivegrid.de) durchläuft OAuth vollständig (DCR + Consent + Token „authentication successful"), wird aber beim Reconnect abgelehnt („Got new credentials, but hivegrid-staging rejected them on reconnect"). Ursache: die DNS-Rebinding-Protection des MCP-SDK (StreamableHTTPServerTransport) lehnt bei konfigurierten allowedOrigins jeden Request ohne Origin-Header ab (Invalid Origin header: undefined, SDK streamableHttp.js Origin-Validierung). Native MCP-Clients (Claude Code/Desktop, Cursor, Inspector-CLI) senden prinzipbedingt keinen Origin-Header → kein benannter Produkt-Client konnte verbinden; der Auth-Check läuft vorher und war erfolgreich (deshalb wirkte es wie ein Token-Problem).
  • Fix (dieser Branch, apps/mcp/src/transport.ts): buildOriginAllowlist() — die allowedOrigins-Allowlist wird nur noch an das SDK durchgereicht, wenn der Request tatsächlich einen Origin-Header trägt (Browser-Kontext, z.B. browser-basierter MCP Inspector); ohne Origin-Header entfällt nur der Origin-Check, der Host-Check (allowedHosts) bleibt für jeden Request aktiv. DNS-Rebinding ist ein Browser-Angriff — für native Clients ohne Origin ist die Prüfung gegenstandslos. Unit-Test apps/mcp/src/transport.test.ts. Proof lokal: pnpm --filter @hivegrid/mcp typecheck + test (9 Tests) + build grün.
  • Rückbau der Client-Anbindung beim Testenden (falls gewünscht): claude mcp remove hivegrid-staging -s local entfernt Server + gespeicherte Credentials aus der lokalen Claude-Code-Config (nichts davon liegt im Repo); Access-Tokens laufen nach 1h ab. Test-Leads aus hg_lead_create sind normale InboxLeads im Tenant und können in der Lead-Inbox archiviert/gelöscht werden (z.B. cmr57zk0f000001mptutf1qf8, „E2E Proof").
  • Nach Merge/Deploy: in Claude Code /mcp → hivegrid-staging → re-authenticate; danach sollten die 8 hg_*-Tools nutzbar sein → formaler DoD-Haken.

2026-07-03 (Akeshan) — formaler Produkt-Client-Proof mit Claude Code (DoD-Haken gesetzt):

  • Nach Deploy des Origin-Fixes: Claude Code (claude mcp add --transport http hivegrid-staging https://staging-mcp.hivegrid.de) verbindet per OAuth (Consent im Browser durch den User), alle 8 hg_*-Tools verfügbar.
  • Read: hg_pipeline_list → Sales-Pipeline mit 5 Stages (tenant-gescopt). Write: hg_activity_add mit confirm=true auf dem E2E-Test-Lead → Activity cmr59h3wu000001ji93ee3f6a („note_added").
  • Querschnitt in der Staging-DB verifiziert: AuditEvent action=mcp.activity.add, targetType=lead, sourceModule=mcp, outcome=success + Activity-Zeile mit Proof-Text.

2026-07-09 Abschluss-Entscheidung Raffael — Done auf Basis Staging-Proof:

  • Produktentscheidung: Wenn der MCP-Flow auf Staging funktioniert, ist das Ticket abschlussfähig; Prod muss dafür nicht separat getestet werden, weil der aktuelle Stand später promotet werden kann. Der Prod-Promote auf mcp.hivegrid.de wird bewusst noch nicht gemacht und ist kein DoD-Blocker.
  • Live-Recheck Staging:
    • GET https://staging-mcp.hivegrid.de/.well-known/oauth-protected-resource liefert 200 mit resource=https://staging-mcp.hivegrid.de, Authorization-Server https://staging-app.hivegrid.de und den MCP-Scopes.
    • Unauthentifizierter POST https://staging-mcp.hivegrid.de/ liefert 401 mit WWW-Authenticate: Bearer realm="HiveGrid MCP", resource_metadata="https://staging-mcp.hivegrid.de/.well-known/oauth-protected-resource" und Klartext „MCP requests require a bearer access token."
  • Zusammen mit dem 2026-07-03 Produkt-Client-Proof (Claude Code OAuth, Tools, Read/Write, Audit/Activity) ist die DoD erfüllt: 8/8 DoD = 100 % done.
  • Damit ist der DoD-Punkt „echter Client per OAuth + je 1 Read-/Write-Tool" vollständig erfüllt. Offen am Ticket: Prod-Rollout mcp.hivegrid.de (DoD 1) + VD-MCP-Screens (Raffael/David).

Früherer Proof lokal (MCP-Runtime vor OAuth-Nachzug):

  • pnpm --filter @hivegrid/mcp build
  • pnpm --filter @hivegrid/config test
  • pnpm --filter @hivegrid/web test -- app/routes.test.ts app/modules/i18n/visible-shell-copy-i18n.test.ts app/utils/app/PublicRouteSegments.test.ts app/utils/app/HostRouting.server.test.ts
  • pnpm typecheck
  • pnpm run verify:env-drift
  • pnpm run verify:deploy-readiness
  • pnpm run verify:deploy-workflow
  • pnpm run verify:docker-baseline
  • docker build --target mcp --build-arg APP_REVISION=ci-smoke-revision -t hivegrid-mcp:smoke .
  • bash scripts/docker-mcp-runtime-smoke.sh hivegrid-mcp:smoke

Abhängigkeiten

  • blocked-by: VR-P22a (Read-Endpoints + OpenAPI-Vertrag), VR-P22b (API-Key-Auth/Scopes/Rate-Limit) — beide fällig 17.07., also vor dem MCP-Slot (18.07.) → kein Konflikt.
  • blocks: — (Endpunkt der v2-MCP-Schiene)
  • Ersetzt: VR-P25 (HiveMind/RAG, zurückgestellt)

Quellen

  • AD-26 (KI→MCP-Pivot) · MCP-Spec Rev. 2025-11-25 (modelcontextprotocol.io: Authorization/Transports/Tools/Security) · TypeScript-SDK (github.com/modelcontextprotocol/typescript-sdk) · Anthropic „Writing tools for agents"