Extentos MCP

Servidor MCP

Servidor MCP

El servidor MCP de Extentos (@extentos/mcp-server\) es un paquete npm que un agente de IA (Claude Code, Cursor, Windsurf, Cline) instala una vez y luego usa para añadir capacidades de gafas inteligentes Meta Ray-Ban a una app nativa de iOS o Android. Expone un conjunto reducido de herramientas deterministas en 10 categorías — descubrimiento, generación, configuración del agente, credenciales, analíticas, guía, validación, simulación, preparación para producción y documentación — además de una CLI para vinculación de cuentas, consentimiento de telemetría y comprobación de actualizaciones. Este es el manual operativo del agente.

El servidor MCP es la forma en que un agente de IA — Claude Code, Cursor, Windsurf, Cline o cualquier host compatible con el Protocolo de Contexto de Modelo — opera Extentos. El agente invoca herramientas deterministas; el servidor prepara al agente sobre qué capacidades exponen las gafas, devuelve patrones de código canónicos del SDK en Kotlin y Swift, genera el andamiaje del proyecto, gestiona sesiones del simulador y consulta trazas de depuración. El servidor en sí no tiene herramienta de planificación — los agentes son mejores planificadores que los conjuntos de expresiones regulares. Las herramientas son primitivas tipadas que el agente compone en secuencia.

Esta página es la página de inicio de la sección — qué es el servidor, las herramientas en resumen, el flujo canónico dirigido por el agente, opciones de configuración, la CLI y cómo funciona el modelo de autenticación. Las subpáginas cubren cada tema en profundidad.

Instalación

claude mcp add extentos -- npx -y @extentos/mcp-server@latest

Para hosts que no sean Claude Code, consulta el prompt del agente o las rutas de instalación manual en JSON. Referencia completa de instalación en /docs/mcp-server/install.

Las herramientas, por categoría

El servidor expone una superficie de herramientas determinista (verificada en mcp-server/src/tools/definitions.ts), organizada en 10 categorías. Las categorías son el mapa mental del agente; un agente que entiende en qué categoría reside una herramienta puede decidir cuándo llamarla. El catálogo completo siempre actualizado es la referencia de herramientas generada.

1. Descubrimiento y referencia del SDK (3 herramientas)

Las primeras llamadas en cualquier tarea nueva. Económicas, todas locales, sin efectos secundarios.

Herramienta	Qué hace
getPlatformInfo	Devuelve el catálogo estático de la plataforma — versión de la librería, la lista de capacidades del SDK que exponen las gafas, niveles por proveedor. Siempre la primera llamada correcta.
getCapabilityGuide	Uso mínimo por funcionalidad en Kotlin + Swift — forma de la llamada, argumentos de configuración, advertencias. Se combina con getPlatformInfo (que nombra las funcionalidades) para indicar al agente cómo invocar cada una.
getCodeExample	Composiciones canónicas completas en ambos lenguajes. Comienza con assistant_agent_loop (el flujo canónico de asistente de voz de la Fase 4) y agent_driven_e2e_full_loop (la prueba E2E dirigida por el agente). También cubre voice_qa_assistant, barge_in_speak, photo_describe_voice, live_transcription_ui, voice_notes, connection_page_setup, byok_anthropic, display_browse_detail, display_media_gallery y video_frames_ml. Toma de aquí al escribir código de manejo. La lista completa enumerada se genera en /docs/reference/mcp-tools.

2. Configuración y Generación

Herramienta	Qué hace
generateConnectionModule	Andamiaje en un solo paso — módulo de arranque, cableado Gradle/SPM, dependencias, permisos, manifiesto. Flujo de dos llamadas: la primera llamada sin ubicación devuelve una pregunta sobre dónde debe residir ExtentosConnectionPage; la segunda llamada con la ubicación elegida devuelve el conjunto completo de archivos.
getConnectionPageConfig / setConnectionPageConfig	Lee / escribe la configuración por proyecto de la página de conexión (tokens de tematización + visibilidad de secciones) que mantiene el panel/servidor.
regenerateConnectionPageFile / adoptConnectionPageFile	Sincroniza el archivo extentos.connection-page.json confirmado con la configuración del servidor — regenerar (servidor→archivo) o adoptar (archivo→servidor).

Después del andamiaje, el agente escribe sus propias clases de manejo contra las primitivas del SDK expuestas por getCapabilityGuide / getCodeExample. El código de manejo es la superficie de autoría del cliente — no hay un paso de initSpec o de población de DSL.

3. Configuración y uso del agente (3 herramientas)

Con ámbito de cuenta — requieren una cuenta vinculada y están limitadas por proyecto mediante la concesión de acceso MCP (por defecto Lectura+Escritura).

Herramienta	Qué hace
getAssistantConfig / setAssistantConfig	Lee o cambia la configuración del asistente gestionada por el panel de un proyecto — el modelo OpenAI Realtime, la voz, el modelo de memoria (compactación) y el modo de memoria dentro de la sesión. set es una actualización parcial, valida cada valor contra el catálogo y muestra el impacto en el coste de un cambio de modelo.
getGatewayUsage	Lee el uso del gateway gestionado del proyecto + el coste exacto durante una ventana reciente — recuentos de tokens y USD de precio de lista del libro mayor de facturación, desglosados por modelo. Solo metadatos, nunca transcripciones o contenido.

4. Credenciales (2 herramientas)

Con ámbito de cuenta + limitadas por proyecto. Escritura sin conocimiento — el secreto nunca pasa a través del agente.

Herramienta	Qué hace
getCredentialStatus	Lee si la clave API de OpenAI (BYOK) y la identidad de compilación Meta DAT de un proyecto están establecidas — solo una pista enmascarada + fecha de actualización, nunca el valor.
setCredential	Inicia la entrada de una credencial con escritura sin conocimiento — devuelve un enlace al panel donde el propietario que ha iniciado sesión pega el secreto directamente en la bóveda cifrada. Por diseño, no acepta argumento de secreto.

5. Analíticas (1 herramienta)

Herramienta

Qué hace

getProjectAnalytics

Lee las analíticas de producción de un proyecto — telemetría agregada de instalaciones publicadas en App Store / Play Store (eventos, instalaciones activas, por evento / día / proveedor / plataforma). Solo metadatos, con ámbito de cuenta, verificación de propiedad, limitadas por la concesión de Analíticas. Vacío hasta que la app se publica y envía eventos atestiguados en producción (usa getEventLog para el flujo en vivo de desarrollo/simulación).

6. Guía de Implementación (2 herramientas)

Herramientas para tareas secundarias que el agente llama durante la composición.

Herramienta	Qué hace
getVoiceCommandGuidance	Analiza frases de activación/comando propuestas en busca de problemas de UX (colisiones, ambigüedad, palabras difíciles de reconocer, conflictos con palabras de activación de Meta) antes de conectarlas a un consumidor de glasses.audio.transcriptions().
getPermissions	Deduce los permisos exactos de plataforma, requisitos de Meta DAT y necesidades de servicio en primer plano a partir de la lista de capacidades. Se ejecuta al añadir o eliminar una primitiva de tu manejador.

7. Validación (2 herramientas)

Controles de corrección. Se ejecutan después de cambios estructurales (nueva capacidad declarada, dependencia actualizada, manifiesto editado).

Herramienta	Qué hace
inspectIntegration	Instantánea de proyecto de solo lectura — manifiesto, hashes de archivos generados, lista de dependencias, configuración de página de conexión. Ejecutar antes de ediciones manuales para entender el estado actual.
validateIntegration	Verificación de corrección de todo el proyecto — manifiesto, archivos generados, dependencia declarada, permisos cubren capacidades declaradas, bootstrap llama a ExtentosGlasses.create(...), versiones de toolchain, sugerencias de servicio en primer plano para flujos de captura continua. La puerta previa a pruebas.

8. Simulación

Aprovisiona y opera sesiones de simulador basadas en navegador, además de las herramientas de prueba dirigidas por agente que cierran el ciclo de extremo a extremo sin intervención humana.

Herramienta	Qué hace
createSimulatorSession	Obtiene o crea una sesión en modo navegador en extentos.com/s. Devuelve la simulación guardada para este proyecto si existe (estado: "resumed"), o crea una nueva (estado: "active"). Adjunta automáticamente la aplicación en ejecución a través del puente local cuando es accesible; de lo contrario, emite un fragmento BuildConfig.EXTENTOS_SESSION_URL (Android) o una carga útil extentos.session.plist (iOS). Pasa resetFresh: true para rotar el sessionId y empezar desde cero.
ensureSimulatorBrowser	Abre + confirma una pestaña de navegador del simulador conectada — la precondición para flujos de cámara e inyección.
completeAuthLink	Después de que createSimulatorSession devuelve estado: "auth_required" (la instalación anónima necesita vincularse para crear sesiones), consulta el backend hasta que el usuario finaliza el registro, luego persiste el token de portador en ~/.extentos/auth.json.
getEventLog	Obtiene trazas de eventos estructurados de una sesión. Valores de filtro: all (sin filtro) más los siete chips errors, voice, camera, display, ai, lifecycle, custom — un chip por evento, con errors absorbiendo severidad≥warn independientemente de la modalidad. Además cursor, follow, limit para alcance a nivel de traza. La herramienta de depuración principal.
getSimulatorStatus	Lee el estado actual de una sesión en vivo — fase, hardware listo, roles adjuntos, flujos de capacidad activos, valores de alternancia actuales.
injectTranscript / injectAssistantUtterance / assertToolCalled	Activa una palabra de activación o un turno del asistente, luego verifica qué herramienta llamó el modelo — el ciclo E2E dirigido por agente, sin necesidad de humanos.
setSimVideo / setSimDevice	Introduce un video de prueba en la cámara simulada; cambia el modelo de dispositivo simulado (p. ej., rayban_display para ejercitar la ruta de visualización).
getDisplayState / injectInput	Lee el árbol de visualización actualmente renderizado + dirige la entrada de visualización (seleccionar / navegar / volver).

9. Producción (2 herramientas)

Verificaciones previas al envío.

Herramienta	Qué hace
getProductionChecklist	Lista de verificación de preparación para producción personalizada basada en capacidades declaradas + nombres de manejadores — cableado de credenciales, auditoría de permisos, requisitos de servicio en primer plano (cuando se usa captura continua), eliminación de URL del simulador de compilaciones de lanzamiento, preparación para ficha de tienda.
getCredentialGuide	Configuración paso a paso de credenciales para proveedores de IA de producción — anthropic, openai, google_cloud_vision, google_translate, google_gemini, deepl, azure_cognitive, aws_bedrock, huggingface, o custom — más registro DAT de Meta.

10. Documentación y búsqueda (1 herramienta)

Herramienta

Qué hace

searchDocs

Busca documentación de Extentos por tema o palabra clave. Para asistentes de voz, lee primero assistant_runtime; conversation_runtime es el runtime de Fase 3 obsoleto (solo referencia de migración). Otros temas alineados: voice_integration, agent_e2e_testing, managed_gateway, conversation_memory, display, más el conjunto conceptual estable — getting_started, custom_handlers (el documento canónico de composición del SDK), simulator_browser_mode, event_log_schema, toggles, library_api, permissions, multi_platform_projects. Los ID de tema son estables; la entrada de la herramienta en vivo es la autoritativa.

Referencia completa por herramienta con esquemas de entrada, formas de respuesta y ejemplos prácticos: /docs/mcp-server/tools.

El flujo canónico dirigido por agente

En un proyecto nuevo, el agente invoca las herramientas en este orden:

1. getPlatformInfo({ sections: ["version", "capabilities"], glasses: "meta_rayban" })
2. getCodeExample({ pattern: "assistant_agent_loop" })  // Phase-4 voice assistant; or whatever pattern fits
3. getCapabilityGuide({ feature: "<each primitive the handler will use>" })
4. generateConnectionModule({ platform, glasses, appPackage })
   → returns "needs_placement" question
5. generateConnectionModule({ ... placement: "<chosen>" })
   → writes scaffold files (ExtentosBootstrap, manifest, etc.)
6. <agent writes handler class(es)> against the SDK primitives
   <agent updates extentos.manifest.json's `capabilities` array>
7. validateIntegration()
   → ✓ all good (or returns structured errors to fix)
8. createSimulatorSession({ glasses })
   → returns sessionId; auto-opens browser at extentos.com/s/<id>
   → if running app is reachable via local bridge, it auto-attaches
9. <developer interacts with the simulator; capability events flow into the backend>
10. getEventLog({ sessionId, filter: "errors" })  → debug
    getSimulatorStatus({ sessionId })             → status

Para iteración: editar código del manejador → reconstruir + reinstalar → la aplicación se adjunta automáticamente a la misma sesión del simulador (sin recrear, la URL es estable). Antes de enviar: getProductionChecklist y getCredentialGuide.

Configuración

El servidor MCP lee estas variables de entorno (verificadas en mcp-server/src/):

Variable	Predeterminado	Qué hace
EXTENTOS_BACKEND_URL	Backend de producción	Anula la URL del backend (tools/util/backendClient.ts). Para desarrollo local del propio Extentos.
EXTENTOS_CONFIG_DIR	~/.extentos	Anula el directorio de configuración/autenticación (telemetry/consent.ts).
EXTENTOS_TELEMETRY	no establecido (predeterminado de consentimiento)	Establecer a 0 para rechazar la telemetría sin ejecutar el comando de consentimiento de la CLI.
EXTENTOS_NO_AUTO_OPEN	no establecido	Establecer a 1 para deshabilitar la apertura automática del navegador al crear la sesión del simulador (útil en entornos sin interfaz gráfica).

Referencia completa de configuración: /docs/mcp-server/configuration.

Subcomandos de CLI

Ejecutar npx @extentos/mcp-server@latest sin argumentos inicia el servidor MCP sobre stdio (la ruta que usa el agente). Con un subcomando, actúa como una CLI de desarrollador:

Subcomando	Qué hace
login	Vincula esta instalación a una cuenta de Extentos mediante el flujo de código de dispositivo (proactivo — útil antes de la primera sesión del simulador, o después de cerrar sesión para revincular).
logout	Limpia ~/.extentos/auth.json. La instalación vuelve al nivel anónimo; la siguiente llamada de sesión del simulador reactivará el flujo de código de dispositivo.
whoami	Aún no implementado (stub de Fase-0). Imprimirá installId, accountId (si está vinculado), nivel, caducidad de autenticación.
setup	Prepara el entorno de compilación local — verifica el PAT de GitHub Packages (read:packages) que necesitan los artefactos transitivos de Meta DAT, además de otros prerrequisitos de dependencias.
accept-privacy	Registra el consentimiento de privacidad (habilita la subida de telemetría).
decline-privacy	Registra el rechazo de privacidad (deshabilita la subida de telemetría).
status	Imprime el estado de consentimiento, ID de instalación, cuenta vinculada, versiones de MCP/biblioteca.
update	Busca actualizaciones del servidor MCP (no-op en instalaciones con npx @latest).

Referencia completa de CLI: /docs/mcp-server/auth.

Modelo de autenticación

El servidor MCP es anónimo por defecto. El descubrimiento, las guías de capacidades, los ejemplos de código, la validación, la búsqueda en documentos, la simulación en dispositivo y las pruebas en hardware real funcionan sin necesidad de iniciar sesión. Tres cosas vinculan una cuenta gratuita: acuñar sesiones del simulador de navegador (createSimulatorSession, HTTP 402), el paso de andamiaje generateConnectionModule (acuña tu clave de proyecto vinculada a la cuenta — mismo flujo de código de dispositivo 402; la primera llamada informativa es anónima), y las herramientas de proyecto con alcance de cuenta (configuración del asistente, credenciales, escrituras de página de conexión, analíticas — HTTP 401).

El flujo de código de dispositivo: la primera llamada restringida devuelve status: "auth_required" con una URL de verificación. El agente llama a completeAuthLink para sondear el backend; el desarrollador se registra con una cuenta gratuita solo de correo electrónico en la URL (Google o correo + contraseña, sin pago); el backend emite un token; la llamada a la herramienta original se reintenta automáticamente. Después de la vinculación, las sesiones del simulador son ilimitadas.

Las herramientas, la generación de código, la validación, el SDK y el simulador de navegador de Extentos son gratuitos — no hay tarifa por puesto ni suscripción para construir y distribuir. La única superficie que mide el uso es la puerta de enlace de IA gestionada detrás del asistente de voz de la Fase 4. Modelo de autenticación completo: /docs/mcp-server/auth; precios: /docs/resources/pricing.

Privacidad y telemetría

En la primera ejecución, el servidor MCP inyecta un aviso de privacidad único en la respuesta. La telemetría es anónima (etiquetada con installId, sin código fuente ni datos personales) y se descarta al continuar por defecto — mismo patrón que Vercel CLI, Astro, Vite. Rechazar en cualquier momento:

npx @extentos/mcp-server@latest decline-privacy
# or
EXTENTOS_TELEMETRY=0 (env var, persistent for the shell)

El contenido del aviso de privacidad está en mcp-server/src/index.ts (constante PRIVACY_NOTICE). El aviso se muestra una vez por instalación a través de claimFirstPrivacyNotice — nunca se repite.

Hosts MCP compatibles

Verificado para funcionar con:

• Claude Code — objetivo principal. Instalación en una línea mediante claude mcp add.
• Cursor — configuración JSON en ~/.cursor/mcp.json.
• Windsurf — configuración JSON en ~/.codeium/windsurf/mcp_config.json.
• Cline — configuración JSON en los ajustes MCP de Cline.
• Cualquier host compatible con MCP — añade el bloque JSON estándar mcpServers.extentos.

El servidor MCP habla el protocolo MCP estándar sobre stdio (@modelcontextprotocol/sdk); no existen rutas de código específicas del host en el lado del servidor. Pasos de instalación por host: /docs/mcp-server/agents.

El puente local — bucle de desarrollo de vinculación automática

Cuando el servidor se inicia, abre un escucha HTTP 127.0.0.1:31337/whoami (mcp-server/src/localBridge.ts). La biblioteca de Extentos en la aplicación del desarrollador sondea este endpoint en tiempo de ejecución para conocer el installId de su host MCP. El resultado: cada llamada a createSimulatorSession desde el agente vincula automáticamente la aplicación en ejecución a la nueva sesión — sin reconstrucción, sin pegar URL.

Rutas de alcance:

• Emulador de Android: http://10.0.2.2:31337/whoami (alias NAT de loopback del host)
• Simulador de iOS: http://localhost:31337/whoami (comparte el espacio de nombres de red del host)
• Teléfono Android físico por USB: adb reverse tcp:31337 tcp:31337 una vez, luego localhost:31337 desde el dispositivo
• Teléfono celular o agente alojado en la nube: el sondeo expira. El agente usa la ruta de incrustación de URL en su lugar — createSimulatorSession devuelve un fragmento BuildConfig.EXTENTOS_SESSION_URL (Android) o una carga útil extentos.session.plist (iOS) que el desarrollador pega y luego reconstruye la aplicación una vez. Menos elegante que la vinculación automática, pero funciona en cualquier topología.

Vinculado solo a 127.0.0.1. El installId no es un secreto — es el mismo valor que el MCP envía a api.extentos.com en cada llamada de herramienta. No se necesita autenticación en esta capa.

Si el puerto 31337 está en uso (raro; otra instancia MCP ya en ejecución), el inicio registra una advertencia y continúa. La vinculación automática falla silenciosamente para esa sesión; el desarrollador usa la ruta de incrustación de URL hasta que el puerto se libere.

Estado

• Paquete: @extentos/mcp-server en npm (licencia MIT)
• Motores: Node.js 20+
• Pre-1.0 — las API pueden cambiar entre versiones menores hasta que se cierre el bucle de pruebas de hardware. Fija una versión exacta si necesitas reproducibilidad entre sesiones.

Relacionado

• Inicio rápido con un agente de IA — instala el servidor y recorre un bucle de desarrollo real
• Referencia de herramientas — API completa por herramienta
• Configuración — variables de entorno, archivos de configuración, ajustes de tiempo de instalación
• Autenticación — flujo de código de dispositivo, vinculación de cuenta, comandos CLI de autenticación
• Agentes compatibles — instrucciones de instalación por host
• Arquitectura — cómo encaja el servidor MCP en el sistema Extentos más amplio
• Transporte vs simulación de aplicación — qué hace realmente el simulador que el MCP intermedia

Relacionado

Inicio rápido con un agente de IA

Instala el servidor Extentos MCP y deja que tu agente de IA genere capacidades de gafas inteligentes Meta Ray-Ban en una aplicación nativa iOS o Android. Gratis para empezar.

Arquitectura

Cómo encaja Extentos — agente de IA, servidor MCP, SDK nativo Kotlin/Swift, tres transportes (Meta DAT, simulador de navegador, simulador local en memoria) y el backend.

Transporte vs simulación de aplicación

El Mock Device Kit de Meta simula la capa de transporte; Extentos simula la capa de aplicación — voz, captura de fotos y la experiencia de uso. Ambos importan.

Instalar el servidor MCP

Cómo instalar el servidor Extentos MCP (@extentos/mcp-server) en cualquier agente de codificación de IA compatible con MCP — Claude Code, Cursor, Windsurf, Cline y otros. Comandos de instalación por host, ubicaciones de archivos de configuración, fragmentos JSON para copiar y pegar, pasos para reiniciar y verificar, fijación de versión, actualización, solución de errores comunes e instrucciones de desinstalación. Rutas de instalación verificadas para cada host compatible.

Referencia de herramientas

El servidor Extentos MCP expone un conjunto ajustado de herramientas deterministas en categorías deterministas — descubrimiento + referencia del SDK, generación, guía, validación, simulación, producción, configuración del agente y búsqueda. Referencia por herramienta que cubre parámetros de entrada, formas de respuesta, cuándo llamar a cada herramienta y ejemplos prácticos. Verificado a partir de las definiciones de herramientas reales y las implementaciones de manejadores en @extentos/mcp-server.

Configuración

Configura @extentos/mcp-server — variables de entorno, los archivos de estado ~/.extentos (id de instalación, autenticación, consentimiento) y el proveedor predeterminado.

Autenticación

Cómo funciona la autenticación de Extentos. Casi todo se ejecuta sin cuenta; solo el simulador de navegador necesita inicio de sesión, a través del flujo de código de dispositivo OAuth 2.0. Sin pago.

Agentes compatibles

Diferencias por host para agentes de codificación de IA que ejecutan Extentos — Claude Code, Cursor, Windsurf, Cline, integrados en IDE. Alcance, alcance multiplataforma, soporte MCP.

Gafas inteligentes de Apple

Gafas inteligentes de Apple para desarrolladores externos — acceso al SDK, modelo de aplicación, distribución, capacidades e IA, y su lugar en el panorama de gafas inteligentes de 2026.

Instalar el servidor MCP