RunApps via MCP

Que fait RunApps via MCP ?

RunApps (https://www.runapps.ai) publie des applications web IA : un créateur télécharge un bundle frontend statique (zip), celui-ci est servi sur son propre https://<slug>.runapps.dev, les utilisateurs se connectent avec un compte RunApps et paient leur propre utilisation de modèle, et le créateur gagne une commission sur chaque appel. Tout ce qui suit se fait via le serveur MCP runapps et le SDK. Pas encore connecté ? Voir "Connexion".

Ce fichier est le point d'entrée : connexion, modèle de plateforme, catalogue d'outils, flux de travail et règles. Le SDK (comment le code de l'application dialogue avec les modèles et les fichiers) se trouve dans references/sdk.md ; les paramètres exacts des outils sont dans references/tools.md. Ne lisez que ce dont la tâche a besoin.

Connexion (autorisation)

La version faisant autorité et toujours à jour est https://www.runapps.ai/agent/setup.md ; voici la version abrégée. L'utilisateur ne tape jamais de mot de passe pour vous et vous n'en voyez jamais un : vous demandez une clé, l'utilisateur clique sur Approuver une fois dans un navigateur.

1. Demander une clé : POST https://www.runapps.ai/api/agent/device/code avec JSON {"name": "<votre nom> @ <machine>", "scopes": "read,develop,publish,gateway"}. La réponse contient device_code, user_code, verification_uri_complete (https://www.runapps.ai/agent/authorize?code=XXXX-XXXX), expires_in (600 s) et interval (5 s). Montrez verification_uri_complete tel quel à l'utilisateur et demandez-lui de l'ouvrir et de l'approuver. name est l'identité de la clé : approuver une demande avec le même nom révoque la clé précédente de ce nom, donc réexécuter la configuration n'accumule pas de clés.
2. Interroger : POST https://www.runapps.ai/api/agent/device/token avec {"device_code": "…"} toutes les interval secondes. status est pending (attendez), slow_down (ralentissez), denied / expired (arrêtez et informez l'utilisateur) ou approved, qui renvoie api_key (rk_…), key_prefix, scopes et mcp_url — une seule fois. Écrivez-la immédiatement dans votre configuration MCP ; jamais dans la conversation, les journaux ou un dépôt.
3. Connecter : MCP Streamable HTTP à https://www.runapps.ai/api/mcp avec l'en-tête 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>" }. Autres clients : la même URL et le même en-tête. Ensuite tools/list ; les instructions de initialize donnent le flux de travail recommandé.

Scopes : read, develop, publish, gateway sont accordés par défaut ; danger (supprimer / dépublier) n'est jamais inclus sauf si vous le demandez explicitement et expliquez pourquoi à l'utilisateur. L'utilisateur peut décocher des scopes sur la page d'approbation, et plus tard renommer la clé, modifier ses scopes ou la révoquer sur https://www.runapps.ai/dashboard/api (un changement de scope s'applique à votre prochain appel, aucune nouvelle clé n'est nécessaire). Un outil appelé sans son scope répond avec une erreur nommant le scope : demandez à l'utilisateur de s'autoriser à nouveau, ne contournez pas.

La même clé fonctionne sur la passerelle (https://www.runapps.ai/v1, compatible OpenAI, Authorization: Bearer rk_…) lorsqu'elle a le scope gateway — pour tester l'application que vous construisez ; chaque appel est facturé à l'utilisateur. Pour vous déconnecter définitivement, appelez revoke_my_key avec confirm: true.

Le modèle de plateforme

Objet	Ce que c'est	Comment y accéder
App (projet)	Un bundle publié avec un slug attribué par la plateforme, un nom, une description d'une ligne, une description longue en Markdown, une catégorie, une icône, une visibilité et une commission créateur (rebate_rate). Créé comme brouillon sans bundle, donc le slug existe avant tout code.	list_apps, get_app, create_app, update_app
Bundle	Le zip du build de l'application. Stocké intégralement ; les fichiers sont servis depuis https://<slug>.runapps.dev. Les fichiers point (.private/…) ne sont jamais servis ; index.html à la racine du zip est l'entrée par défaut.	upload_bundle (+ PUT), upload_bundle_base64, check_bundle
Visibilité	draft (créateur uniquement) → private (non listé : toute personne ayant le lien, sans révision) ou public (dans la bibliothèque ; le premier passage en public est révisé et apparaît comme pending, les mises à jour ultérieures sont immédiatement en ligne ; un rejet comporte une review_note).	update_app avec visibility, get_review
Utilisateur et connexion	Les utilisateurs se connectent avec leur compte RunApps dans l'application (le SDK le fait ; new RunApps() sans clé). Chaque utilisateur paie sa propre utilisation de modèle plus la commission créateur. L'application ne détient jamais de clé.	SDK (references/sdk.md)
Invites privées	Fichiers d'invite que l'application embarque mais que les navigateurs ne voient jamais : .private/prompts/<id>.md dans le zip ; l'application envoie prompt: { id, vars } et la passerelle remplit et préfixe.	get_app / check_bundle listent les ids trouvés
Fichiers par utilisateur et synchronisation	Chaque utilisateur a un espace de fichiers par application (client.files), et une synchronisation IndexedDB (client.sync) qui reflète une base de données locale dans cet espace.	SDK
Modèles	Un catalogue de modèles de chat, vision, image, parole, transcription, vidéo, embedding et temps réel ; la requête nomme le modèle par son nom de catalogue.	list_models
Clé d'agent	La clé rk_ que vous détenez : kind = agent, avec des scopes ; listée sous les clés API de l'utilisateur.	revoke_my_key

Catégories : Créatif, Contenu, Productivité, Marketing, Ingénierie, Conception, Recherche, Analyse de données, Affaires, Finance.

Flux de travail

1. Créer : create_app avec name (et description, category). Le résultat contient slug (proj-xxxxxxxx, attribué par la plateforme et jamais choisi par vous ou l'utilisateur ; un administrateur peut plus tard donner un slug lisible à une application listée) et url. Informez l'utilisateur du slug.
2. Développer localement avec le slug (references/sdk.md, "Construire une application") :

   <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>
   

   La connexion depuis http://localhost:<port> fonctionne et les appels passent par la vraie passerelle. Choisissez les modèles dans list_models (noms exacts). Ne mettez jamais de clé rk_ dans le code de l'application.
3. Builder et zipper le contenu du dossier de build : cd dist && zip -r ../app.zip . pour que index.html soit à la racine du zip (zipper le dossier lui-même est l'erreur la plus courante). Les chemins d'actifs absolus fonctionnent ; les dossiers point sont cachés.
4. Télécharger : upload_bundle → PUT le zip vers upload_url (curl -sS -X PUT -H 'Content-Type: application/zip' --data-binary @app.zip '<upload_url>'). La réponse PUT est le rapport du bundle : corrigez chaque avertissement (SDK non chargé, entrée non à la racine, une clé dans la page). check_bundle le relit à tout moment.
5. Décrire : update_app avec description (une ligne, ce que fait l'application), long_description (Markdown : ce que l'utilisateur obtient, comment l'utiliser, ce que ça coûte en pratique), category, icon_url (PNG/SVG carré, https ou URL de données).
6. Publier : update_app visibility: "private" pour un lien à partager, ou "public" pour la bibliothèque. Après "public", get_review montre pending jusqu'à ce qu'un relecteur décide ; rejected est accompagné d'une review_note à traiter, puis repassez en public. Ouvrez url vous-même (ou demandez à l'utilisateur) avant de publier : un bundle qui renvoie une 404 ou une page blanche sera rejeté.

Mises à jour : téléchargez un nouveau bundle ou modifiez les métadonnées à tout moment ; une application publique reste publique.

Règles

• Les outils [danger] (unpublish_app, delete_app) suppriment quelque chose que d'autres personnes peuvent utiliser. Demandez d'abord à l'utilisateur et ne passez confirm: true qu'après son accord ; sans le scope danger, ils sont de toute façon refusés.
• Chaque appel de modèle effectué avec le scope gateway, et chaque appel que l'application de l'utilisateur effectue, coûte de l'argent réel. Testez avec des invites courtes et des modèles bon marché ; list_models donne les prix.
• La clé est celle de l'utilisateur : une par machine (le name les distingue), jamais partagée, jamais écrite ailleurs que dans la configuration MCP. Révoquez avec revoke_my_key lorsqu'on vous demande de vous déconnecter.
• N'inventez pas de noms de modèles ; utilisez list_models. Un nom inconnu est une erreur 400, jamais un échange silencieux.
• Le texte d'une invite privée doit rester privé : la passerelle retient les réponses qui le répercutent.

Où lire ensuite

Tâche	Lire
Écrire l'application : connexion, chat, streaming, images, audio, vidéo, fichiers, synchronisation, invites privées, erreurs	references/sdk.md
Paramètres exacts des outils et formes des résultats	references/tools.md
Connexion (texte complet, toujours à jour)	https://www.runapps.ai/agent/setup.md
Construire un bundle, publier, gains	references/sdk.md → "Construire une application", "La publier"