runapps/skills

RunApps vía MCP

RunApps (https://www.runapps.ai) publica aplicaciones web de IA: un creador sube un bundle frontend estático (zip), se sirve en su propia https://<slug>.runapps.dev, los usuarios inician sesión con una sola cuenta de RunApps y pagan por su propio uso de modelos, y el creador gana una comisión por cada llamada. Todo lo siguiente se realiza a través del servidor MCP runapps y el SDK. ¿Aún no conectado? Consulta "Conexión".

Este archivo es el punto de entrada: conexión, modelo de plataforma, catálogo de herramientas, flujo de trabajo y reglas. El SDK (cómo el código de la app se comunica con modelos y archivos) está en references/sdk.md; los parámetros exactos de las herramientas están en references/tools.md. Lee solo lo que la tarea necesite.

Conexión (autorización)

La versión autorizada y siempre actual es https://www.runapps.ai/agent/setup.md; esta es la forma resumida. El usuario nunca escribe una contraseña por ti y tú nunca ves una: pides una clave, el usuario hace clic en Aprobar una vez en un navegador.

1. Solicitar una clave: POST https://www.runapps.ai/api/agent/device/code con JSON {"name": "<tu nombre> @ <máquina>", "scopes": "read,develop,publish,gateway"}. La respuesta tiene device_code, user_code, verification_uri_complete (https://www.runapps.ai/agent/authorize?code=XXXX-XXXX), expires_in (600 s) e interval (5 s). Muestra verification_uri_complete al usuario textualmente y pídele que la abra y la apruebe. name es la identidad de la clave: aprobar una solicitud con el mismo nombre revoca la clave anterior de ese nombre, por lo que volver a ejecutar la configuración no acumula claves.
2. Preguntar: POST https://www.runapps.ai/api/agent/device/token con {"device_code": "…"} cada interval segundos. status es pending (esperar), slow_down (retroceder), denied / expired (detener e informar al usuario) o approved, que devuelve api_key (rk_…), key_prefix, scopes y mcp_url — una sola vez. Escríbela inmediatamente en tu configuración MCP; nunca en la conversación, registros o repositorios.
3. Conectar: MCP Streamable HTTP en https://www.runapps.ai/api/mcp con el encabezado 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>" }. Otros clientes: la misma URL y encabezado. Luego tools/list; las instructions de initialize dan el flujo de trabajo recomendado.

Ámbitos: read, develop, publish, gateway se otorgan por defecto; danger (eliminar / despublicar) nunca se incluye a menos que lo solicites explícitamente y le digas al usuario por qué. El usuario puede desmarcar ámbitos en la página de aprobación, y luego renombrar la clave, cambiar sus ámbitos o revocarla en https://www.runapps.ai/dashboard/api (un cambio de ámbito se aplica a tu próxima llamada, no se necesita una nueva clave). Una herramienta llamada sin su ámbito responde con un error nombrando el ámbito: pide al usuario que autorice de nuevo, no lo eludas.

La misma clave funciona en la puerta de enlace (https://www.runapps.ai/v1, compatible con OpenAI, Authorization: Bearer rk_…) cuando tiene el ámbito gateway — para probar la app que construyes; cada llamada se factura al usuario. Para desconectarte definitivamente, llama a revoke_my_key con confirm: true.

El modelo de plataforma

Objeto	Qué es	Cómo acceder a él
App (proyecto)	Un bundle publicado con un slug asignado por la plataforma, nombre, descripción de una línea, descripción larga en Markdown, categoría, icono, visibilidad y comisión del creador (rebate_rate). Se crea como borrador sin bundle, por lo que el slug existe antes que cualquier código.	list_apps, get_app, create_app, update_app
Bundle	El zip del build de la app. Almacenado completo; los archivos se sirven desde https://<slug>.runapps.dev. Los archivos ocultos (.private/…) nunca se sirven; index.html en la raíz del zip es la entrada predeterminada.	upload_bundle (+ PUT), upload_bundle_base64, check_bundle
Visibilidad	draft (solo el creador) → private (no listado: cualquiera con el enlace, sin revisión) o public (en la biblioteca; el primer cambio a público se revisa y muestra pending, las actualizaciones posteriores son inmediatas; un rechazo incluye review_note).	update_app con visibility, get_review
Usuario e inicio de sesión	Los usuarios inician sesión con su cuenta de RunApps dentro de la app (el SDK lo hace; new RunApps() sin clave). Cada usuario paga su propio uso de modelos más la comisión del creador. La app nunca tiene una clave.	SDK (references/sdk.md)
Prompts privados	Archivos de prompt que la app envía pero el navegador nunca ve: .private/prompts/<id>.md en el zip; la app envía prompt: { id, vars } y la puerta de enlace lo completa y lo antepone.	get_app / check_bundle listan los ids encontrados
Archivos por usuario y sincronización	Cada usuario tiene un espacio de archivos por app (client.files), y una sincronización IndexedDB (client.sync) que replica una base de datos local en él.	SDK
Modelos	Un catálogo de modelos de chat, visión, imagen, voz, transcripción, video, embedding y tiempo real; la solicitud nombra el modelo por su nombre de catálogo.	list_models
Clave de agente	La clave rk_ que tienes: kind = agent, con ámbitos; listada bajo las Claves API del usuario.	revoke_my_key

Categorías: Creativo, Contenido, Productividad, Marketing, Ingeniería, Diseño, Investigación, Análisis de Datos, Negocios, Finanzas.

Flujo de trabajo

1. Crear: create_app con name (y description, category). El resultado tiene slug (proj-xxxxxxxx, asignado por la plataforma y nunca elegido por ti o el usuario; un administrador puede luego darle uno legible a una app listada) y url. Informa al usuario el slug.
2. Desarrollar localmente contra el slug (references/sdk.md, "Construir una app"):

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

   El inicio de sesión desde http://localhost:<puerto> funciona y las llamadas pasan por la puerta de enlace real. Elige modelos de list_models (nombres exactos). Nunca pongas una clave rk_ en el código de la app.
3. Construir y comprimir el contenido de la carpeta de build: cd dist && zip -r ../app.zip . para que index.html esté en la raíz del zip (comprimir la carpeta en sí es el error más común). Las rutas absolutas de assets funcionan; las carpetas ocultas están ocultas.
4. Subir: upload_bundle → PUT del zip a upload_url (curl -sS -X PUT -H 'Content-Type: application/zip' --data-binary @app.zip '<upload_url>'). La respuesta del PUT es el informe del bundle: corrige cada advertencia (SDK no cargado, entrada no en la raíz, una clave en la página). check_bundle lo relee en cualquier momento.
5. Describir: update_app con description (una línea, qué hace), long_description (Markdown: qué obtiene el usuario, cómo usarlo, cuánto cuesta en la práctica), category, icon_url (PNG/SVG cuadrado, https o data URL).
6. Publicar: update_app visibility: "private" para un enlace para compartir, o "public" para la biblioteca. Después de "public", get_review muestra pending hasta que un revisor decide; rejected viene con review_note para actuar, luego establecer public de nuevo. Abre url tú mismo (o pide al usuario que lo haga) antes de publicar: un bundle que da 404 o muestra una página en blanco será rechazado.

Actualizaciones: sube un nuevo bundle o cambia metadatos en cualquier momento; una app pública permanece pública.

Reglas

• Las herramientas [danger] (unpublish_app, delete_app) eliminan algo que otras personas pueden estar usando. Pregunta primero al usuario y pasa confirm: true solo después de que esté de acuerdo; sin el ámbito danger serán rechazadas de todas formas.
• Cada llamada a modelo hecha con el ámbito gateway, y cada llamada que hace la app del usuario, cuesta dinero real. Prueba con prompts cortos y modelos baratos; list_models da los precios.
• La clave es del usuario: una por máquina (el name las distingue), nunca compartida, nunca escrita en ningún lugar excepto la configuración MCP. Revoca con revoke_my_key cuando se te pida desconectar.
• No inventes nombres de modelos; usa list_models. Un nombre desconocido es un 400, nunca un reemplazo silencioso.
• El texto de un prompt privado debe permanecer privado: la puerta de enlace retiene las respuestas que lo repiten.

Dónde leer a continuación

Tarea	Leer
Escribir la app: inicio de sesión, chat, streaming, imágenes, audio, video, archivos, sincronización, prompts privados, errores	references/sdk.md
Parámetros exactos de las herramientas y formas de resultado	references/tools.md
Conexión (texto completo, siempre actual)	https://www.runapps.ai/agent/setup.md
Construir un bundle, publicar, ganancias	references/sdk.md → "Construir una app", "Publicarla"