RunApps via MCP

Was macht RunApps via MCP?

RunApps (https://www.runapps.ai) veröffentlicht KI-Web-Apps: Ein Ersteller lädt ein statisches Frontend-Bundle (Zip) hoch, es wird unter einer eigenen URL https://<slug>.runapps.dev bereitgestellt, Benutzer melden sich mit einem RunApps-Konto an und bezahlen für ihre eigene Modellnutzung, und der Ersteller erhält eine Gebühr für jeden Aufruf. Alles unten wird über den runapps MCP-Server und das SDK erledigt. Noch nicht verbunden? Siehe „Verbinden".

Diese Datei ist der Einstiegspunkt: Verbinden, das Plattformmodell, der Toolkatalog, der Workflow und die Regeln. Das SDK (wie der App-Code mit Modellen und Dateien spricht) ist in references/sdk.md; genaue Tool-Parameter sind in references/tools.md. Lies nur das, was die Aufgabe benötigt.

Verbinden (Autorisierung)

Die maßgebliche, immer aktuelle Version ist https://www.runapps.ai/agent/setup.md; dies ist die Kurzform. Der Benutzer gibt niemals ein Passwort für dich ein und du siehst nie eines: Du fragst nach einem Schlüssel, der Benutzer klickt einmal im Browser auf „Genehmigen".

1. Schlüssel anfordern: POST https://www.runapps.ai/api/agent/device/code mit JSON {"name": "<your name> @ <machine>", "scopes": "read,develop,publish,gateway"}. Die Antwort enthält device_code, user_code, verification_uri_complete (https://www.runapps.ai/agent/authorize?code=XXXX-XXXX), expires_in (600 s) und interval (5 s). Zeige dem Benutzer verification_uri_complete wörtlich und bitte ihn, sie zu öffnen und zu genehmigen. name ist die Identität des Schlüssels: Die Genehmigung einer Anfrage mit demselben Namen widerruft den vorherigen Schlüssel dieses Namens, sodass bei wiederholter Einrichtung keine Schlüsselansammlung entsteht.
2. Abrufen (Polling): POST https://www.runapps.ai/api/agent/device/token mit {"device_code": "…"} alle interval Sekunden. status ist pending (warten), slow_down (langsamer machen), denied / expired (stoppen und dem Benutzer mitteilen) oder approved, was api_key (rk_…), key_prefix, scopes und mcp_url zurückgibt – einmalig. Schreibe es sofort in deine MCP-Konfiguration; niemals in die Konversation, Protokolle oder ein Repository.
3. Verbinden: MCP Streamable HTTP unter https://www.runapps.ai/api/mcp mit Header Authorization: Bearer <api_key>. Claude Code: claude mcp add --transport http runapps "https://www.runapps.ai/api/mcp" --header "Authorization: Bearer <api_key>". Codex: [mcp_servers.runapps] url = "https://www.runapps.ai/api/mcp", http_headers = { Authorization = "Bearer <api_key>" }. Andere Clients: dieselbe URL und derselbe Header. Dann tools/list; die instructions von initialize geben den empfohlenen Workflow an.

Bereiche (Scopes): read, develop, publish, gateway werden standardmäßig gewährt; danger (löschen / zurückziehen) ist niemals enthalten, es sei denn, du fragst explizit danach und teilst dem Benutzer den Grund mit. Der Benutzer kann auf der Genehmigungsseite Bereiche abwählen und später den Schlüssel umbenennen, seine Bereiche ändern oder ihn unter https://www.runapps.ai/dashboard/api widerrufen (eine Bereichsänderung gilt für deinen nächsten Aufruf, es ist kein neuer Schlüssel erforderlich). Ein Tool, das ohne seinen Bereich aufgerufen wird, antwortet mit einem Fehler, der den Bereich nennt: Bitte den Benutzer, erneut zu autorisieren, umgehe dies nicht.

Derselbe Schlüssel funktioniert am Gateway (https://www.runapps.ai/v1, OpenAI-kompatibel, Authorization: Bearer rk_…), wenn er den Bereich gateway hat – zum Testen der von dir erstellten App; jeder Aufruf wird dem Benutzer in Rechnung gestellt. Um die Verbindung endgültig zu trennen, rufe revoke_my_key mit confirm: true auf.

Das Plattformmodell

Objekt	Was es ist	Wie du es erreichst
App (Projekt)	Ein veröffentlichtes Bundle mit einem von der Plattform zugewiesenen slug, Name, einzeiliger Beschreibung, Markdown-Langbeschreibung, Kategorie, Symbol, Sichtbarkeit und Erstellungsgebühr (rebate_rate). Wird als Entwurf ohne Bundle erstellt, sodass der Slug existiert, bevor Code geschrieben wird.	list_apps, get_app, create_app, update_app
Bundle	Das Zip der App-Builds. Wird als Ganzes gespeichert; Dateien werden daraus unter https://<slug>.runapps.dev ausgeliefert. Dot-Dateien (.private/…) werden niemals ausgeliefert; index.html im Zip-Root ist der Standardeinstiegspunkt.	upload_bundle (+ PUT), upload_bundle_base64, check_bundle
Sichtbarkeit	draft (nur Ersteller) → private (nicht gelistet: jeder mit dem Link, keine Überprüfung) oder public (in der Bibliothek; der erste Wechsel zu öffentlich wird überprüft und zeigt pending, spätere Updates sind sofort live; eine Ablehnung enthält einen review_note).	update_app mit visibility, get_review
Benutzer & Anmeldung	Benutzer melden sich mit ihrem RunApps-Konto innerhalb der App an (das SDK erledigt das; new RunApps() ohne Schlüssel). Jeder Benutzer bezahlt seine eigene Modellnutzung plus die Erstellergebühr. Die App hält niemals einen Schlüssel.	SDK (references/sdk.md)
Private Prompts	Prompt-Dateien, die die App ausliefert, die der Browser aber nie sieht: .private/prompts/<id>.md im Zip; die App sendet prompt: { id, vars } und das Gateway füllt sie aus und stellt sie voran.	get_app / check_bundle listet die gefundenen IDs auf
Benutzerdateien & Synchronisation	Jeder Benutzer hat einen Dateibereich pro App (client.files), und eine IndexedDB-Synchronisation (client.sync) spiegelt eine lokale Datenbank dorthin.	SDK
Modelle	Ein Katalog von Chat-, Vision-, Bild-, Sprach-, Transkriptions-, Video-, Embedding- und Echtzeitmodellen; die Anfrage nennt das Modell mit seinem Katalognamen.	list_models
Agent-Key	Der rk_-Schlüssel, den du besitzt: kind = agent, begrenzt; aufgeführt unter den API-Schlüsseln des Benutzers.	revoke_my_key

Kategorien: Creative, Content, Productivity, Marketing, Engineering, Design, Research, Data Analysis, Business, Finance.

Workflow

1. Erstellen: create_app mit name (und description, category). Das Ergebnis enthält slug (proj-xxxxxxxx, von der Plattform zugewiesen und niemals von dir oder dem Benutzer gewählt; ein Admin kann einer gelisteten App später einen lesbaren geben) und url. Teile dem Benutzer den Slug mit.
2. Lokal entwickeln mit dem Slug (references/sdk.md, „Eine App erstellen"):

   <script src="https://www.runapps.ai/sdk/latest.js"></script>
   <script>
     const client = new RunApps({ project: "<slug>" });
     const r = await client.chat.create({ model: "Claude Sonnet 4.6", messages: [{ role: "user", content: "hi" }] });
   </script>
   

   Die Anmeldung von http://localhost:<port> funktioniert und Aufrufe gehen durch das echte Gateway. Wähle Modelle aus list_models (genaue Namen). Setze niemals einen rk_-Schlüssel in den App-Code.
3. Erstellen und Zippen des Inhalts des Build-Ordners: cd dist && zip -r ../app.zip ., sodass index.html im Zip-Root ist (das Zippen des Ordners selbst ist der häufigste Fehler). Absolute Asset-Pfade funktionieren; Dot-Ordner sind ausgeblendet.
4. Hochladen: upload_bundle → PUT des Zips an upload_url (curl -sS -X PUT -H 'Content-Type: application/zip' --data-binary @app.zip '<upload_url>'). Die PUT-Antwort ist der Bundle-Bericht: Behebe jede Warnung (SDK nicht geladen, Einstieg nicht im Root, ein Schlüssel in der Seite). check_bundle liest es jederzeit erneut.
5. Beschreiben: update_app mit description (einzeilig, was die App tut), long_description (Markdown: was der Benutzer bekommt, wie man sie nutzt, was sie praktisch kostet), category, icon_url (quadratisches PNG/SVG, https oder data URL).
6. Veröffentlichen: update_app visibility: "private" für einen zu teilenden Link oder "public" für die Bibliothek. Nach "public" zeigt get_review pending, bis ein Prüfer entscheidet; rejected kommt mit einem review_note, auf den reagiert werden muss, dann setze public erneut. Öffne url selbst (oder bitte den Benutzer darum), bevor du veröffentlichst: Ein Bundle, das einen 404 oder eine leere Seite ergibt, wird abgelehnt.

Updates: Lade jederzeit ein neues Bundle hoch oder ändere Metadaten; eine öffentliche App bleibt öffentlich.

Regeln

• [danger]-Tools (unpublish_app, delete_app) entfernen etwas, das andere möglicherweise verwenden. Frage zuerst den Benutzer und übergib confirm: true nur, nachdem er zugestimmt hat; ohne den danger-Bereich werden sie ohnehin abgelehnt.
• Jeder Modellaufruf, der mit dem gateway-Bereich getätigt wird, und jeder Aufruf, den die App des Benutzers tätigt, kostet echtes Geld. Teste mit kurzen Prompts und günstigen Modellen; list_models gibt Preise an.
• Der Schlüssel gehört dem Benutzer: einer pro Maschine (der name unterscheidet sie), niemals geteilt, niemals woanders als in der MCP-Konfiguration gespeichert. Widerrufe mit revoke_my_key, wenn du aufgefordert wirst, die Verbindung zu trennen.
• Erfinde keine Modellnamen; verwende list_models. Ein unbekannter Name führt zu einem 400-Fehler, niemals zu einem stillen Austausch.
• Der Text eines privaten Prompts muss privat bleiben: Das Gateway enthält Antworten, die ihn wiedergeben.

Wo du als nächstes lesen solltest

Aufgabe	Lesen
Schreiben der App: Anmeldung, Chat, Streaming, Bilder, Audio, Video, Dateien, Synchronisation, private Prompts, Fehler	references/sdk.md
Genaue Tool-Parameter und Ergebnisstrukturen	references/tools.md
Verbinden (Volltext, immer aktuell)	https://www.runapps.ai/agent/setup.md
Ein Bundle erstellen, veröffentlichen, verdienen	references/sdk.md → „Eine App erstellen", „Veröffentlichen"