MCP Media Upload — UX & Architektur
Stand: 2026-10-18 · Status: Phase 1 implementiert (Sessions + MCP begin/complete/status) · Phase 2 teilweise: Claude-Widget (MCP App) implementiert
Ziel: Medien-Workflows in ChatGPT, Claude und Cursor so erleben wie bei spezialisierten KI-Video-Tools (z. B. Higgsfield): Datei in die Chat-Oberfläche ziehen, der Host lädt direkt ins Storage — ohne Base64 durch das LLM oder enge Tool-Argument-Limits.
Nutzer-Doku (heute): Claude MCP — Redaktion · API: AgencyOS Medien-Upload
Was / Warum
| Was | Spezifikation für Presigned-Upload-Sessions, Abschluss-Tool und Host-Fallbacks neben dem bestehenden cockpit_upload_media. |
| Warum | Große Videos und PDFs scheitern an MCP-Argumentgrößen (hosted Claude ~32 KB decoded), Base64 bläht Tokens und Latenz auf, und Redaktion erwartet „Drop → fertige Bunny-URL“. |
| Wer | Redaktion (Claude/ChatGPT), Agenten-Entwickler, Betrieb (Bunny, Audit). |
| Wo (heute) | POST /api/agencyos/v1/media/upload, MCP cockpit_upload_media, Dashboard /api/upload. |
Ist-Zustand (cockpitOS)
AgencyOS POST /api/agencyos/v1/media/upload
Implementierung: apps/dashboard/src/app/api/agencyos/v1/media/upload/route.ts
| Modus | Transport | Limits (dekodiert) |
|---|---|---|
| URL-Fetch | JSON { url, folder? } | ~10 MB Bild / ~100 MB Video |
| Base64 | JSON { base64, mimeType?, filename?, folder? } | gleich |
| Raw Binary | Content-Type: image/* | video/* | application/octet-stream + Query folder, filename | gleich |
Antwort: { success: true, bunnyUrl }. Bereits auf Bunny (.b-cdn.net) → URL wird bestätigt, kein Re-Upload.
Auth: AgencyOS Bearer (sk_agencyos_…, MCP User Token, OAuth MCP Connect). Audit: entityType: media-upload.
MCP cockpit_upload_media
Proxy auf dieselbe Route — nur url oder base64 (kein Raw-Multipart aus dem MCP-Prozess).
Downstream-Nutzung (unverändert gültig):
- Social:
cockpit_create_social_draft/mediaUrls[]nach Upload - Content Pool:
cockpit_content_pool_attach_assets - Mediathek-Liste:
cockpit_list_media - Angebote/PDF:
attachmentPdfUrlnach Upload
Dashboard (Redaktion)
Multipart POST /api/upload → Bunny, inkl. Mediathek-MediaFile-Eintrag. Das ist der Referenz-Flow für große Dateien in der UI — nicht über MCP-Base64.
Phase 1 — Upload-Sessions (live)
| Schritt | API / MCP |
|---|---|
| Begin | POST /api/agencyos/v1/media/upload-sessions · MCP cockpit_media_upload_begin |
| Bytes | PUT uploadUrl aus der Antwort (Proxy-Route, kein Bunny-AccessKey im Client) |
| Complete | POST …/upload-sessions/{sessionId}/complete · MCP cockpit_media_upload_complete |
| Status | GET …/upload-sessions/{sessionId} · MCP cockpit_media_upload_status |
Bunny-Pfad (gleiche Pipeline wie bestehende Uploads):
| Szenario | Pfad |
|---|---|
| Agent / Social / Pool (Standard) | agencyos/uploads/{sessionId}_{dateiname} — identisch zu folder: agencyos/uploads bei cockpit_upload_media |
Explizites folder im begin | {folder}/{sessionId}_{dateiname} |
Mediathek (registerMediaFile: true + centerId) | centers/{centerId}/general/{name}-{timestamp}.{ext} (bzw. office/service) — wie Dashboard POST /api/upload |
Upload-Bytes und Complete nutzen uploadToBunnyCDN bzw. HEAD am CDN; Mediathek-Einträge folgen dem MediaFile-Schema inkl. optional Vector-Sync (wie Dashboard).
Referenz-UX (Zielbild)
Prinzipien
- Ein Byte-Pfad pro Upload — Host oder Browser → Storage; MCP trägt nur Session-IDs und Metadaten.
- Kompatibel mit heutigen Tools —
bunnyUrlbleibt die Währung für Social, Pool, Offers. - Optional Mediathek —
completekannMediaFileanlegen (centerId,entityType, Workflow-Status). - Explizite Fallbacks — wenn der Host keine Datei an Storage durchreicht, klare nächste Schritte (siehe unten).
MCP-Host-Landschaft (2025–2026)
Was die Clients heute können — relevant für Priorisierung und Fallback-Texte in Tool-Beschreibungen.
| Host | Mechanismus | Grenzen / Hinweise |
|---|---|---|
| Claude Desktop / Cowork / Cursor (stdio) | Chat-Anhänge; Agent kann Bytes als file_data + filename an Tools übergeben (Community-Muster, z. B. Talonic MCP) | Lokal oft ohne harte JSON-Grenze; trotzdem kein Ziel für 100 MB-Video durch Tool-Args |
| Claude.ai (hosted Connector) | Tool-Call-Argumente ~32 KB decoded (Production-Messung, Community) | Base64 in Tools unbrauchbar für echte Medien → Presigned- oder URL-Flow Pflicht |
| ChatGPT MCP Apps | _meta["openai/fileParams"] — Host injiziert { file_id, download_url, mime_type?, file_name? } | Server lädt von download_url; Widget: window.openai.uploadFile / selectFiles |
| MCP Spec (Entwurf) | SEP-2356 — deklarative inputFiles / requestedFiles, Wire: Data-URI | Noch nicht überall in Hosts; Cockpit soll beide Welten unterstützen (Presigned + fileParams-Download) |
| MCP Elicitation | Form (requestedSchema) oder URL-Mode (url + elicitationId) | URL-Mode für „Upload im Browser“ ohne Bytes in MCP |
Quellen (extern): OpenAI Apps SDK — fileParams, MCP Elicitation, MCP File Uploads WG / SEP-2356.
Was cockpitOS allein liefern kann vs. Host-Abhängigkeit
| Lieferung | Nur cockpitOS | Braucht Host-Verhalten |
|---|---|---|
| Presigned Upload Session + Complete API | Ja | — |
MCP cockpit_media_upload_begin / _complete | Ja | — |
Raw POST …/media/upload (bereits da) | Ja | Client muss Binary senden (Script, curl, Partner-App) |
| Chat-Dropzone → direkt Bunny ohne LLM | Teilweise | Host muss Presigned PUT ausführen oder fileParams-Download anbieten |
| Native Datei-Picker in MCP Tool-UI | Nein (ohne Spec) | SEP-2356 / Host-Implementierung |
| ChatGPT Widget-Upload in MCP App | Nein | OpenAI window.openai.* in eingebetteter UI |
| Claude hosted: große Datei in Tool-Args | Nein | Immer Out-of-band (Presigned, Elicitation-URL, User-Dashboard) |
Fazit: cockpitOS kann End-to-End-Storage und Agent-Orchestrierung shippen; das Higgsfield-Gefühl im Chat hängt am Host (file injection, Presigned-Executor, SEP-2356). Bis dahin: Presigned + Elicitation-URL + Dashboard-Fallback.
Ziel-API (Phase 1 — umgesetzt)
1. Session beginnen
POST /api/agencyos/v1/media/upload-sessions
Body (Beispiel):
{
"filename": "hero.mp4",
"mimeType": "video/mp4",
"byteSize": 52428800,
"folder": "agencyos/uploads",
"centerId": "optional-uuid",
"entityType": "social",
"intent": "social_draft"
}
Antwort:
{
"success": true,
"sessionId": "mus_…",
"uploadMethod": "PUT",
"uploadUrl": "https://…",
"uploadHeaders": { "Content-Type": "video/mp4", "Content-Length": "52428800" },
"expiresAt": "2026-10-17T12:00:00.000Z",
"maxBytes": 104857600
}
Server: signiertes stateless Token (mus_…, HMAC — kein DB-Schema), Limits/MIME wie media/upload (kein HEIC/HEIF/AVIF).
2. Bytes hochladen
Außerhalb von MCP — PUT/POST an uploadUrl (Bunny Storage API oder presigned Edge-URL).
Optional: GET …/media/upload-sessions/{sessionId} für Status (pending | uploaded | failed | expired).
3. Session abschließen
POST /api/agencyos/v1/media/upload-sessions/{sessionId}/complete
- Prüft Objekt auf Bunny (Größe, MIME, Malware-Heuristik optional)
- Liefert
{ bunnyUrl, mediaFileId?, durationMs? } - Audit wie heutiger Upload
4. MCP-Tools (neu, neben cockpit_upload_media)
| Tool | Rolle |
|---|---|
cockpit_media_upload_begin | Session + Anleitung für Host (uploadUrl, expiresAt, ggf. hostHint) |
cockpit_media_upload_complete | Finalize + Mediathek-Option |
cockpit_media_upload_status | Polling für langsame Clients |
cockpit_upload_media bleibt für URL-Fetch und kleine Base64-Assets (< Limits).
Tool-Metadaten (ChatGPT): geplante _meta["openai/fileParams"] auf einem providedFile-Argument von complete, sobald Host die Datei injiziert — Server lädt von download_url und überspringt Presigned PUT wenn Session mode=host_injected.
Phasen
Phase 0 — Doku & Vertrag (dieses Dokument)
- Gemeinsames Zielbild, Fallback-Matrix, Abhängigkeiten Host vs. Cockpit
- Kein VERSION-Bump nötig
Phase 1 — Presigned Session (cockpit-only) ✅
- REST:
upload-sessions+complete+status+ PUT…/content - MCP:
cockpit_media_upload_begin/_complete/_status - Tests: Session-Pfad, Signatur, Complete-Lifecycle (Unit)
- Doku: api-agencyos-integration.md,
exports/cockpitos-tools.json
Phase 2 — Host-Integration & Elicitation
Claude web / desktop — MCP-App „Dropzone“ ✅ (2026-10-18)
- Tool
cockpit_media_upload_widgetöffnet im Chat eine Dropzone (UI-Resourcetext/html;profile=mcp-app,registerAppToolaus@modelcontextprotocol/ext-apps). - Mehrfach-Upload (0.1.752): Mehrere Dateien in einem Durchgang (Picker
multipleoder Drag-and-Drop) — Upload nacheinander (eine Session pro Datei), Fortschritt im Widget, alle erfolgreichenbunnyUrlgesammelt perui/update-model-context. - Das Widget ruft
cockpit_media_upload_begin→ PUT direkt anuploadUrl(CSPconnectDomains= Dashboard-Origin) →cockpit_media_upload_completeüber den Host auf; der Bearer bleibt im MCP-Server. Ergebnis (bunnyUrl,mediaFileId) geht perui/update-model-contextzurück an das Modell. _meta.ui.domain= sha256(Connector-URL) für stabile Sandbox-Origin; versionierte UI-URI; Health-Diagnose (/health→mcpUi).- Fallback unverändert: Hosts ohne MCP-Apps nutzen weiter begin → PUT → complete bzw.
cockpit_upload_media. - Betrieb, Env, Checkliste, Troubleshooting:
docs/MCP_APPS_CLAUDE_WEB.md. - Noch offen: Abnahme in einer echten Claude-Instanz (CSP/Domain), ChatGPT
fileParams, Elicitation-URL-Modus.
Weitere Punkte dieser Phase:
- ChatGPT: Schema +
_meta.openai/fileParamsfürcomplete; Handler: Download von Host-URL → Bunny (Idempotenz profile_id) - Claude hosted: Tool-Beschreibung + Elicitation URL-Mode auf kurzlebige Cockpit-Upload-Seite (Session-token in URL, Same-Origin Upload zu Presigned)
- Cursor / Claude Desktop: Presigned-Anleitung in Tool-Response; optional SEP-2356 wenn SDK/Host reif
Phase 3 — Produkt-Workflows
| Workflow | Nach Upload |
|---|---|
| Social | cockpit_create_social_draft mit mediaUrls: [bunnyUrl] |
| Content Pool | cockpit_content_pool_attach_assets |
| Mediathek | complete mit registerMediaFile: true + centerId |
| Partner-Intake | Parallele Route oder Session mit intent=partner_intake |
| Angebote/PDF | Wie heute: URL an attachmentPdfUrl |
Optional Phase 3b: Ein MCP-Composite cockpit_upload_and_attach_social (begin → complete → draft) — nur wenn es Tool-Call-Budget spart.
Phase 4 — UX-Polish
- Dashboard „Agent-Upload“-Status (Sessions pro Integration)
- Rate-Limits / Quota pro Org
- Virus-Scan-Hook (async) vor
publishedin Mediathek
Fallback-Flows (für Tool-Beschreibungen & Redaktion)
A — Kleine Bilder / externe URL
Weiter cockpit_upload_media mit url (Shop-Logo, Karma-Vorschau-URL) oder kleinem Base64.
B — Große Datei, Host unterstützt fileParams (ChatGPT)
Agent ruft complete mit vom Host injizierter Datei auf; Server pullt download_url.
C — Große Datei, Claude.ai hosted
cockpit_media_upload_begin- Elicitation-URL oder Link in Antwort: „Upload im Browser abschlieben“ (Session-Token)
cockpit_media_upload_completenach Browser-Upload (oder Pollingstatus)
D — Große Datei, Claude Desktop / Cursor
- User hängt Datei an Chat an
- Bevorzugt: Host führt Presigned PUT aus (wenn/unter welchen Bedingungen der Host das kann, ist host-spezifisch — bis Bestätigung: Fallback E)
- Fallback E: User lädt in Dashboard-Mediathek hoch; Agent nutzt
cockpit_list_media+ bestehende URL
E — Script / CI
Raw POST /api/agencyos/v1/media/upload mit Binary-Body (bereits produktiv).
F — Partner / MallCrew
Unverändert Partner-v1 Upload; Agent verknüpft über Intake-API — nicht durch MCP-Chat-Args.
Sicherheit & Betrieb
- Auth: Gleiche Policy wie
media/upload(agency-os-action-policy) - SSRF: URL-Fetch-Pfad bleibt separat; Presigned nur für Client→Bunny, nicht für beliebige Ziel-URLs
- Limits: 10 MB / 100 MB (oder konfigurierbar pro Integration)
- Audit: Session-ID,
sessionId→bunnyUrl, Integration, optionalcenterId - Env: bestehende Bunny-Variablen; keine neuen Secrets für Phase 1
- Abgelaufene Sessions: GC-Job (Cron) — siehe CRON-SETUP.md (Eintrag bei Implementierung)
MCP-Parität (Phase 1)
-
packages/mcp-cockpit-os— Tool-Registrierung + Katalog -
exports/cockpitos-tools.json— Export (nach Build) -
api-agencyos-integration.md— REST-Abschnitt -
mcp-tool-referenz.md— Kurzreferenz - MCP-App-Widget (Claude):
cockpit_media_upload_widget, Tool-Katalog, Export,docs/MCP_APPS_CLAUDE_WEB.md - Optional: Hinweis in claude-mcp-redaktion-anleitung.md (Redaktion)
Betrieb (Phase 1)
- Kein DB-Schema: Session = signiertes Token (HMAC-SHA256), Ablauf 30 Min (konfigurierbar 1–60 Min per
ttlSeconds).db_structure.md: keine Änderung. - Secret (optional):
COCKPIT_MEDIA_UPLOAD_SESSION_SECRET. Ohne Wert wird der Schlüssel ausCOCKPIT_ACTOR_TOKEN_SECRETbzw. dem Bunny-Zugang abgeleitet — keine neue Pflicht-Env, keine Secrets in API-Antworten. - Sicherheit:
PUT …/contentbraucht nur das Session-Token (kurzlebig, an Pfad/MIME/Größe gebunden);complete/statusbrauchen den AgencyOS-Bearer derselben Integration und Center-Zugriff. - Idempotenz:
completelegt pro Bunny-Pfad höchstens einenMediaFilean. - GC-Cron: nicht nötig (stateless); verwaiste Objekte unter
agencyos/uploads/bleiben wie beicockpit_upload_mediabestehen.
So testen (nach Phase 1)
- AgencyOS-Key besorgen (Integration oder MCP OAuth).
beginmitbyteSizeundmimeTypefür Test-PNG (< 1 MB).- PUT an
uploadUrlmit curl. complete→bunnyUrlin Browser öffnen.cockpit_create_social_draftmit dieser URL (Staging-Center).- Negative Tests: abgelaufene Session, falsches MIME, HEIC abweisen.
Offene Fragen
- Bunny: Presigned direkt gegen Storage Zone vs. Upload über Dashboard-Proxy (Bandwidth, CORS)?
- Mediathek: Ist
MediaFilebei jedem Agent-Upload Pflicht oder opt-in (registerMediaFile)? - ChatGPT Mobile: fileParams-Binding fehleranfällig (Community-Issues) — separater QA-Pfad?
- Hosted Claude: Liefert Anthropic jemals Presigned-Executor in Connectors, oder dauerhaft Elicitation-URL?
Verwandte Dokumente
- Content Pool — MCP
- Mediathek & Social Asset Hub
- Epic (intern):
docs/MEDIATHEK-SOCIAL-ASSET-HUB-EPIC.md
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/mcp-media-upload-ux