# 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 - [x] 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. - [x] **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 - [x] **Fallback/Operator-Auth** (API-Key-Bearer → Tenant/User/Scopes aus [[VR-P22b]]); 401+`WWW-Authenticate` - [x] **Read-Tools** (Lead/Contact/Project/Pipeline) tenant-gescopt via `withTenantScope()` + RLS - [x] **Write-Tools** mit `withPermission()` + Client-Confirmation + `auditEvent` + `logActivity`; Annotations gesetzt - [x] Rate-Limit pro Tenant; Output-Limits + Pagination; Zod-Validierung; Prompt-Injection-Härtung; kein Token-Passthrough - [x] Konnektor `tenantHasModule('mcp')`; RLS auf allen Tenant-Tabellen - [x] 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"