Skip to main content

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​

WasSpezifikation für Presigned-Upload-Sessions, Abschluss-Tool und Host-Fallbacks neben dem bestehenden cockpit_upload_media.
WarumGroß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“.
WerRedaktion (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

ModusTransportLimits (dekodiert)
URL-FetchJSON { url, folder? }~10 MB Bild / ~100 MB Video
Base64JSON { base64, mimeType?, filename?, folder? }gleich
Raw BinaryContent-Type: image/* | video/* | application/octet-stream + Query folder, filenamegleich

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: attachmentPdfUrl nach 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)​

SchrittAPI / MCP
BeginPOST /api/agencyos/v1/media/upload-sessions · MCP cockpit_media_upload_begin
BytesPUT uploadUrl aus der Antwort (Proxy-Route, kein Bunny-AccessKey im Client)
CompletePOST …/upload-sessions/{sessionId}/complete · MCP cockpit_media_upload_complete
StatusGET …/upload-sessions/{sessionId} · MCP cockpit_media_upload_status

Bunny-Pfad (gleiche Pipeline wie bestehende Uploads):

SzenarioPfad
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

  1. Ein Byte-Pfad pro Upload — Host oder Browser → Storage; MCP trägt nur Session-IDs und Metadaten.
  2. Kompatibel mit heutigen Tools — bunnyUrl bleibt die Währung für Social, Pool, Offers.
  3. Optional Mediathek — complete kann MediaFile anlegen (centerId, entityType, Workflow-Status).
  4. 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.

HostMechanismusGrenzen / 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-URINoch nicht überall in Hosts; Cockpit soll beide Welten unterstützen (Presigned + fileParams-Download)
MCP ElicitationForm (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​

LieferungNur cockpitOSBraucht Host-Verhalten
Presigned Upload Session + Complete APIJa—
MCP cockpit_media_upload_begin / _completeJa—
Raw POST …/media/upload (bereits da)JaClient muss Binary senden (Script, curl, Partner-App)
Chat-Dropzone → direkt Bunny ohne LLMTeilweiseHost muss Presigned PUT ausführen oder fileParams-Download anbieten
Native Datei-Picker in MCP Tool-UINein (ohne Spec)SEP-2356 / Host-Implementierung
ChatGPT Widget-Upload in MCP AppNeinOpenAI window.openai.* in eingebetteter UI
Claude hosted: große Datei in Tool-ArgsNeinImmer 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)​

ToolRolle
cockpit_media_upload_beginSession + Anleitung für Host (uploadUrl, expiresAt, ggf. hostHint)
cockpit_media_upload_completeFinalize + Mediathek-Option
cockpit_media_upload_statusPolling 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-Resource text/html;profile=mcp-app, registerAppTool aus @modelcontextprotocol/ext-apps).
  • Mehrfach-Upload (0.1.752): Mehrere Dateien in einem Durchgang (Picker multiple oder Drag-and-Drop) — Upload nacheinander (eine Session pro Datei), Fortschritt im Widget, alle erfolgreichen bunnyUrl gesammelt per ui/update-model-context.
  • Das Widget ruft cockpit_media_upload_begin → PUT direkt an uploadUrl (CSP connectDomains = Dashboard-Origin) → cockpit_media_upload_complete über den Host auf; der Bearer bleibt im MCP-Server. Ergebnis (bunnyUrl, mediaFileId) geht per ui/update-model-context zurü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/fileParams für complete; Handler: Download von Host-URL → Bunny (Idempotenz pro file_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​

WorkflowNach Upload
Socialcockpit_create_social_draft mit mediaUrls: [bunnyUrl]
Content Poolcockpit_content_pool_attach_assets
Mediathekcomplete mit registerMediaFile: true + centerId
Partner-IntakeParallele Route oder Session mit intent=partner_intake
Angebote/PDFWie 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 published in 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​

  1. cockpit_media_upload_begin
  2. Elicitation-URL oder Link in Antwort: „Upload im Browser abschlieben“ (Session-Token)
  3. cockpit_media_upload_complete nach Browser-Upload (oder Polling status)

D — Große Datei, Claude Desktop / Cursor​

  1. User hängt Datei an Chat an
  2. Bevorzugt: Host führt Presigned PUT aus (wenn/unter welchen Bedingungen der Host das kann, ist host-spezifisch — bis Bestätigung: Fallback E)
  3. 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, optional centerId
  • 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 aus COCKPIT_ACTOR_TOKEN_SECRET bzw. dem Bunny-Zugang abgeleitet — keine neue Pflicht-Env, keine Secrets in API-Antworten.
  • Sicherheit: PUT …/content braucht nur das Session-Token (kurzlebig, an Pfad/MIME/Größe gebunden); complete/status brauchen den AgencyOS-Bearer derselben Integration und Center-Zugriff.
  • Idempotenz: complete legt pro Bunny-Pfad höchstens einen MediaFile an.
  • GC-Cron: nicht nötig (stateless); verwaiste Objekte unter agencyos/uploads/ bleiben wie bei cockpit_upload_media bestehen.

So testen (nach Phase 1)​

  1. AgencyOS-Key besorgen (Integration oder MCP OAuth).
  2. begin mit byteSize und mimeType für Test-PNG (< 1 MB).
  3. PUT an uploadUrl mit curl.
  4. complete → bunnyUrl in Browser öffnen.
  5. cockpit_create_social_draft mit dieser URL (Staging-Center).
  6. Negative Tests: abgelaufene Session, falsches MIME, HEIC abweisen.

Offene Fragen​

  1. Bunny: Presigned direkt gegen Storage Zone vs. Upload über Dashboard-Proxy (Bandwidth, CORS)?
  2. Mediathek: Ist MediaFile bei jedem Agent-Upload Pflicht oder opt-in (registerMediaFile)?
  3. ChatGPT Mobile: fileParams-Binding fehleranfällig (Community-Issues) — separater QA-Pfad?
  4. Hosted Claude: Liefert Anthropic jemals Presigned-Executor in Connectors, oder dauerhaft Elicitation-URL?

Verwandte Dokumente​

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/mcp-media-upload-ux