# 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** | geplant (NEU — KI→MCP-Pivot) | ## 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**. ## 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), eigener Service-Bereich; **SDK `@modelcontextprotocol/sdk`** (das Gerüst `apps/web/app/modules/mcp/` existiert bereits). Kein stdio, kein deprecated SSE. - **Auth Stufe 1:** **API-Key-Bearer** (aus [[VR-P22b]] — Key → Tenant + User + Scopes). 401 mit `WWW-Authenticate` bei Fehlschlag. **Stufe 2 (später, eigenes Ticket/CR):** OAuth 2.1 (PKCE, RFC 9728 Protected-Resource-Metadata, RFC 8707 Resource-Indicators) für „Connect-in-Minutes". - **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. - **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] | API-Key generieren/rotieren/widerrufen + Scopes; aktive Verbindungen; Setup-Anleitung für Clients (Connector-URL + Key); Audit der MCP-Tool-Aufrufe | ## Definition of Done - [ ] Remote-MCP-Server (Streamable HTTP) erreichbar; Session-Handling; Origin- + Protocol-Version-Checks - [ ] **Auth Stufe 1** (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 (Claude Desktop Custom Connector) verbunden + je 1 Read-/Write-Tool ausgeführt - [ ] (Stufe 2 OAuth 2.1 → Folge-Ticket/CR, nicht in diesem Scope) ## Technische Bausteine - `@modelcontextprotocol/sdk` (Server), `StreamableHTTPServerTransport`; eigener Service (`apps/mcp` oder Bereich in `apps/api`) — **nicht** in RR7-Loader/Action quetschen. - Auth/Scopes/Rate-Limit aus [[VR-P22b]] wiederverwenden; Tenant-Context-Middleware (Reihenfolge: TLS → Origin → Protocol-Version → Token+Audience → 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). ## 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"