Extentos MCP

MCP server

O servidor MCP Extentos (@extentos/mcp-server\) é um pacote npm que um agente de IA (Claude Code, Cursor, Windsurf, Cline) instala uma vez e depois usa para adicionar capacidades de óculos inteligentes Meta Ray-Ban a um aplicativo nativo iOS ou Android. Ele expõe um conjunto enxuto de ferramentas determinísticas em 10 categorias — descoberta, geração, configuração de agente, credenciais, análise, orientação, validação, simulação, prontidão para produção e documentação — além de uma CLI para vinculação de conta, consentimento de telemetria e verificações de atualização. Este é o manual operacional do agente.

O servidor MCP é como um agente de IA — Claude Code, Cursor, Windsurf, Cline ou qualquer host compatível com Model Context Protocol — opera a Extentos. O agente invoca ferramentas determinísticas; o servidor prepara o agente sobre quais capacidades os óculos expõem, retorna padrões canônicos de código SDK em Kotlin e Swift, estrutura o projeto, intermedia sessões de simulador e consulta rastros de depuração. O servidor em si não tem ferramenta de planejamento — agentes são melhores planejadores do que pacotes de regex. Ferramentas são primitivas tipadas que o agente compõe em sequência.

Esta página é a seção de aterrissagem — o que é o servidor, as ferramentas em resumo, o fluxo canônico orientado por agente, botões de configuração, a CLI e como funciona o modelo de autenticação. Subpáginas cobrem cada tópico em profundidade.

Instalação

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

Para hosts que não sejam Claude Code, consulte os caminhos de instalação do prompt do agente ou JSON manual. Referência completa de instalação em /docs/mcp-server/install.

As ferramentas, por categoria

O servidor expõe uma superfície de ferramentas determinística (verificada em mcp-server/src/tools/definitions.ts), organizada em 10 categorias. As categorias são o mapa mental do agente; um agente que entende em qual categoria uma ferramenta vive pode decidir quando chamá-la. O catálogo completo sempre atual é a referência de ferramentas gerada.

1. Descoberta e referência SDK (4 ferramentas)

As primeiras chamadas em qualquer nova tarefa. Baratas, todas locais, sem efeitos colaterais.

Ferramenta	O que faz
getPlatformInfo	Retorna o catálogo estático da plataforma — versão da biblioteca, a lista de capacidades SDK que os óculos expõem, níveis por fornecedor. Sempre a primeira chamada correta.
getCapabilityGuide	Uso mínimo por recurso em Kotlin + Swift — formato da chamada, argumentos de configuração, pegadinhas. Combina com getPlatformInfo (que nomeia os recursos) para dizer ao agente como invocar cada um.
getCodeExample	Composições canônicas completas em ambos os idiomas. Comece com assistant_agent_loop (o fluxo canônico de assistente de voz da Fase 4) e agent_driven_e2e_full_loop (o teste E2E orientado por agente). Também cobre 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 e video_frames_ml. Extraia destes ao escrever código de handler. A lista completa enumerada é gerada em /docs/reference/mcp-tools.
getMigrationGuide	Para aplicativos já construídos sobre Meta DAT bruto — retorna um mapa chaveado pelos seus símbolos DAT existentes para as primitivas Extentos que os substituem, além de um plano de migração ordenado.

2. Configuração e Geração

Ferramenta	O que faz
generateConnectionModule	Estruturação em uma única chamada — módulo bootstrap, integração Gradle/SPM, dependências, permissões, manifesto. Fluxo de duas chamadas: a primeira chamada sem placement retorna uma pergunta perguntando onde ExtentosConnectionPage deve ficar; a segunda chamada com o posicionamento escolhido retorna o conjunto completo de arquivos.
getConnectionPageConfig / setConnectionPageConfig	Ler / escrever a configuração da página de conexão por projeto (tokens de tema + visibilidade de seção) que o painel/servidor mantém.
regenerateConnectionPageFile / adoptConnectionPageFile	Sincronizar o extentos.connection-page.json commitado com a configuração do servidor — regenerar (servidor→arquivo) ou adotar (arquivo→servidor).

Após a estruturação, o agente escreve suas próprias classes de handler contra as primitivas SDK expostas por getCapabilityGuide / getCodeExample. O código do handler é a superfície de autoria do cliente — não há etapa de initSpec ou população de DSL.

3. Configuração e uso do agente (5 ferramentas)

Escopo de conta — exigem uma conta vinculada e são limitadas por projeto pela concessão de acesso MCP (padrão Leitura+Escrita).

Ferramenta	O que faz
getAssistantConfig / setAssistantConfig	Ler ou alterar as configurações de assistente gerenciadas pelo painel de um projeto — o modelo OpenAI Realtime, a voz, o modelo de memória (compactação) e o modo de memória dentro da sessão. set é uma atualização parcial, valida cada valor contra o catálogo e ecoa o impacto de custo de uma mudança de modelo.
getGatewayUsage	Ler o uso do gateway gerenciado do projeto + custo exato em uma janela recente — contagens de tokens e USD a preço de lista do ledger de cobrança, detalhado por modelo. Apenas metadados, nunca transcrições ou conteúdo.

4. Credenciais (2 ferramentas)

Escopo de conta + limitado por projeto. Escrita sem saber — o segredo nunca passa pelo agente.

Ferramenta	O que faz
getCredentialStatus	Ler se a identidade de build Meta DAT de um projeto está definida — uma dica mascarada + apenas atualizado em, nunca o valor.
setCredential	Iniciar entrada de credencial com escrita sem saber — retorna um link do painel onde o proprietário conectado cola o segredo diretamente no cofre criptografado. Não recebe argumento de segredo por design.

5. Análise (1 ferramenta)

Ferramenta

O que faz

getProjectAnalytics

Ler a análise de produção de um projeto — telemetria agregada de instalações enviadas da App Store / Play Store (eventos, instalações ativas, por evento / dia / fornecedor / plataforma). Apenas metadados, escopo de conta, verificação de propriedade, limitado pela concessão de Análise. Vazio até o aplicativo ser lançado e enviar eventos atestados em produção (use getEventLog para o fluxo ao vivo de dev/sim).

6. Orientação de Implementação (2 ferramentas)

Ferramentas de missão secundária que o agente chama durante a composição.

Ferramenta	O que faz
getVoiceCommandGuidance	Analisar frases propostas de ativação / comando para problemas de UX (colisões, ambiguidade, palavras difíceis de reconhecer, conflitos com a palavra de ativação da Meta) antes de conectá-las a um consumidor glasses.audio.transcriptions().
getPermissions	Derivar permissões exatas da plataforma, requisitos Meta DAT e necessidades de serviço em primeiro plano a partir da lista de capacidades. Execute ao adicionar ou remover uma primitiva do seu handler.

7. Validação (2 ferramentas)

Portões de correção. Execute após mudanças estruturais (nova capacidade declarada, dependência atualizada, manifesto editado).

Ferramenta	O que faz
inspectIntegration	Snapshot somente leitura do projeto — manifesto, hashes de arquivos gerados, lista de dependências, configuração da página de conexão. Execute antes de edições manuais para entender o estado atual.
validateIntegration	Verificação de correção do projeto inteiro — manifesto, arquivos gerados, dependência declarada, permissões cobrem capacidades declaradas, bootstrap chama ExtentosGlasses.create(...), versões da toolchain, dicas de serviço em primeiro plano para fluxos de captura contínua. O portão pré-teste.

8. Simulação

Provisiona e opera sessões de simulador baseadas em navegador, além das ferramentas de teste orientadas por agente que fecham o loop de ponta a ponta sem um humano.

Ferramenta	O que faz
createSimulatorSession	Obter-ou-criar uma sessão em modo navegador em extentos.com/s. Retorna o sim salvo para este projeto se existir (status: "resumed"), ou cria um novo (status: "active"). Anexa automaticamente o aplicativo em execução via ponte local quando alcançável; caso contrário, emite um snippet BuildConfig.EXTENTOS_SESSION_URL (Android) ou payload extentos.session.plist (iOS). Rotacionar o sessionId é deleteSimulatorSession e depois criar — não há flag de forçar novo.
ensureSimulatorBrowser	Abrir + confirmar uma aba de navegador de simulador conectada — a pré-condição para fluxos de câmera e injeção.
completeAuthLink	Após createSimulatorSession retornar status: "auth_required" (instalação anônima precisa vincular para criar sessões), consulta o backend até o usuário terminar o cadastro, então persiste o token de portador em ~/.extentos/auth.json.
getEventLog	Buscar rastros de eventos estruturados de uma sessão. Valores de filtro: all (sem filtro) mais os sete chips errors, voice, camera, display, ai, lifecycle, custom — um chip por evento, com errors absorvendo severidade≥aviso independentemente da modalidade. Além de cursor, follow, limit para escopo no nível de rastro. A principal ferramenta de depuração.
getSimulatorStatus	Ler o estado atual de uma sessão ao vivo — fase, hardware pronto, papéis anexados, fluxos de capacidade ativos, valores atuais de alternância.
injectTranscript / injectAssistantUtterance / assertToolCalled	Acionar uma frase de ativação ou um turno de assistente, depois afirmar qual ferramenta o modelo chamou — o loop E2E orientado por agente, sem necessidade de humano.
injectHardwareButton	Pressionar o botão de captura de hardware dos óculos simulados — toque pausa/retoma um fluxo de câmera ao vivo, segurar o interrompe — para que o agente possa exercitar os gestos de privacidade do usuário (e testar o CaptureError.StreamPaused resultante) sem humano.
setSimVideo / setSimDevice	Enviar um vídeo de teste para a câmera simulada; alternar o modelo de dispositivo simulado (ex.: rayban_display para exercitar o caminho de exibição).
getDisplayState / injectInput	Ler a árvore de exibição atualmente renderizada + acionar entrada de exibição (select / navigate / back).

9. Produção (2 ferramentas)

Verificações pré-lançamento.

Ferramenta	O que faz
getProductionChecklist	Checklist personalizado de prontidão para produção baseado nas capacidades declaradas + nomes de handlers — integração de credenciais, auditoria de permissões, requisitos de serviço em primeiro plano (quando captura contínua é usada), remoção de URL de simulador de builds de lançamento, prontidão de listagem na loja.
getCredentialGuide	Configuração de credenciais passo a passo para provedores de IA de produção — anthropic, openai, google_cloud_vision, google_translate, google_gemini, deepl, azure_cognitive, aws_bedrock, huggingface ou custom — além do registro Meta DAT.

10. Documentação e busca (1 ferramenta)

Ferramenta

O que faz

searchDocs

Buscar documentação Extentos por tópico ou palavra-chave. Para assistentes de voz, leia assistant_runtime primeiro. Outros tópicos alinhados: voice_integration, agent_e2e_testing, managed_gateway, conversation_memory, display, além do conjunto conceitual estável — getting_started, custom_handlers (o documento canônico de composição SDK), simulator_browser_mode, simulator_session_lifecycle, event_log_schema, toggles, library_api, permissions, multi_platform_projects. Os IDs de tópico são estáveis; a entrada de ferramenta ao vivo é autoritativa.

Referência completa por ferramenta com esquemas de entrada, formatos de resposta e exemplos trabalhados: /docs/mcp-server/tools.

O fluxo canônico orientado por agente

Em um projeto novo, o agente invoca as ferramentas nesta ordem:

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 iteração: edite o código do handler → reconstrua + reinstale → o aplicativo se anexa automaticamente à mesma sessão de simulador (sem recriar, a URL é estável). Antes de lançar: getProductionChecklist e getCredentialGuide.

Configuração

O servidor MCP lê estas variáveis de ambiente (verificadas em mcp-server/src/):

Variável	Padrão	O que faz
EXTENTOS_BACKEND_URL	Backend de produção	Substituir a URL do backend (tools/util/backendClient.ts). Para desenvolvimento local da própria Extentos.
EXTENTOS_CONFIG_DIR	~/.extentos	Substituir o diretório de configuração/autenticação (telemetry/consent.ts).
EXTENTOS_TELEMETRY	não definido (padrão de consentimento)	Definir como 0 para recusar telemetria sem executar o comando de consentimento da CLI.
EXTENTOS_NO_AUTO_OPEN	não definido	Definir como 1 para desabilitar a abertura automática do navegador na criação de sessão de simulador (útil em ambientes headless).

Referência completa de configuração: /docs/mcp-server/configuration.

Subcomandos da CLI

Executar npx @extentos/mcp-server@latest sem argumentos inicia o servidor MCP via stdio (o caminho que o agente usa). Com um subcomando, ele atua como uma CLI de desenvolvedor:

Subcomando	O que faz
login	Vincula esta instalação a uma conta Extentos via fluxo de código de dispositivo (proativo — útil antes da primeira sessão do simulador, ou após logout para re-vincular).
logout	Limpa ~/.extentos/auth.json. A instalação retorna ao nível anônimo; a próxima chamada de sessão do simulador re-disparará o fluxo de código de dispositivo.
whoami	Ainda não implementado (stub da Fase-0). Imprimirá installId, accountId (se vinculado), nível, expiração da autenticação.
setup	Pré-verifica o ambiente de build local — checa o PAT do GitHub Packages (read:packages) que os artefatos DAT da Meta precisam, para apps que dependem de com.extentos:glasses-meta, além de outros pré-requisitos de dependências.
accept-privacy	Registra consentimento de privacidade (habilita upload de telemetria).
decline-privacy	Registra recusa de privacidade (desabilita upload de telemetria).
status	Imprime estado de consentimento, ID de instalação, conta vinculada, versões do MCP/biblioteca.
update	Verifica atualizações do servidor MCP (sem operação em instalações npx @latest).

Referência completa da CLI: /docs/mcp-server/auth.

Modelo de autenticação

O servidor MCP é anônimo-primeiro. Descoberta, guias de capacidades, exemplos de código, validação, busca de documentação, simulação no dispositivo e testes em hardware real funcionam sem necessidade de login. Três coisas vinculam uma conta gratuita: criação de sessões do simulador de navegador (createSimulatorSession, HTTP 402), a etapa de scaffold generateConnectionModule (ela gera sua chave de projeto vinculada à conta — mesmo fluxo de código de dispositivo 402; a primeira chamada informativa é anônima) e as ferramentas de projeto com escopo de conta (configuração do assistente, credenciais, gravações na página de conexão, análises — HTTP 401).

O fluxo de código de dispositivo: a primeira chamada bloqueada retorna status: "auth_required" com uma URL de verificação. O agente chama completeAuthLink para consultar o backend; o desenvolvedor se cadastra com uma conta gratuita apenas por e-mail na URL (Google ou e-mail + senha, sem pagamento); o backend emite um token; a chamada de ferramenta original tenta novamente automaticamente. Após a vinculação, as sessões do simulador são ilimitadas.

As ferramentas do Extentos, geração de código, validação, SDK e o simulador de navegador são gratuitos — não há taxa por assento ou assinatura para construir e publicar. A única superfície que mede uso é o gateway de IA gerenciado por trás do assistente de voz da Fase-4. Modelo de autenticação completo: /docs/mcp-server/auth; preços: /docs/resources/pricing.

Privacidade e telemetria

Na primeira execução, o servidor MCP injeta um aviso de privacidade único na resposta. A telemetria é anônima (marcada com installId, sem código-fonte ou dados pessoais) e é dispensada ao continuar por padrão — mesmo padrão do Vercel CLI, Astro, Vite. Recuse a qualquer momento:

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

O conteúdo do aviso de privacidade está em mcp-server/src/index.ts (constante PRIVACY_NOTICE). O aviso é mostrado uma vez por instalação via claimFirstPrivacyNotice — nunca se repete.

Hosts MCP compatíveis

Verificado para funcionar com:

• Claude Code — alvo principal. Instalação em uma linha via claude mcp add.
• Cursor — configuração JSON em ~/.cursor/mcp.json.
• Windsurf — configuração JSON em ~/.codeium/windsurf/mcp_config.json.
• Cline — configuração JSON nas configurações MCP do Cline.
• Qualquer host compatível com MCP — insira o bloco JSON padrão mcpServers.extentos.

O servidor MCP fala o protocolo MCP padrão via stdio (@modelcontextprotocol/sdk); não existem caminhos de código específicos por host no lado do servidor. Etapas de instalação por host: /docs/mcp-server/agents.

A ponte local — loop de desenvolvimento com auto-vinculação

Quando o servidor inicia, ele abre um listener HTTP 127.0.0.1:31337/whoami (mcp-server/src/localBridge.ts). A biblioteca Extentos no app do desenvolvedor consulta este endpoint em tempo de execução para aprender o installId do MCP host. O resultado: cada chamada createSimulatorSession do agente anexa automaticamente o app em execução à nova sessão — sem rebuild, sem colar URL.

Caminhos de alcance:

• Emulador Android: http://10.0.2.2:31337/whoami (alias NAT de loopback do host)
• Simulador iOS: http://localhost:31337/whoami (compartilha o namespace de rede do host)
• Celular Android físico via USB: adb reverse tcp:31337 tcp:31337 uma vez, depois localhost:31337 do dispositivo
• Celular ou agente hospedado na nuvem: a consulta expira. O agente usa o caminho de URL embutida — createSimulatorSession retorna um trecho BuildConfig.EXTENTOS_SESSION_URL (Android) ou payload extentos.session.plist (iOS) que o desenvolvedor cola, e então reconstrói o app uma vez. Menos elegante que a auto-vinculação, mas funciona em qualquer topologia.

Vinculado apenas a 127.0.0.1. O installId não é um segredo — é o mesmo valor que o MCP envia para api.extentos.com em cada chamada de ferramenta. Nenhuma autenticação necessária nesta camada.

Se a porta 31337 estiver em uso (raro; outra instância MCP já em execução), o início registra um aviso e continua. A auto-vinculação falha silenciosamente para essa sessão; o desenvolvedor usa o caminho de URL embutida até a porta ser liberada.

Status

• Pacote: @extentos/mcp-server no npm (licença MIT)
• Motores: Node.js 20+
• Pré-1.0 — as APIs podem mudar entre versões menores até o loop de teste de hardware fechar. Fixe uma versão exata se precisar de reprodutibilidade entre sessões.

Relacionados

• Início rápido com um agente de IA — instale o servidor e percorra um loop de desenvolvimento real
• Referência de ferramentas — API completa por ferramenta
• Configuração — variáveis de ambiente, arquivos de configuração, configurações de instalação
• Autenticação — fluxo de código de dispositivo, vinculação de conta, comandos de autenticação da CLI
• Agentes suportados — instruções de instalação por host
• Arquitetura — como o servidor MCP se encaixa no sistema Extentos mais amplo
• Transporte vs simulação de app — o que o simulador que o MCP intermedia realmente faz

[

Alibaba Qianwen AI Glasses

Alibaba Qianwen AI Glasses para desenvolvedores terceirizados — a plataforma de Skills da 千问AI硬件开放平台, integração de ferramentas MCP, modelo de app, distribuição, capacidades e IA, e onde se encaixa no cenário de óculos inteligentes de 2026.

](https://extentos.com/docs/ecosystem/platforms/alibaba-qianwen)[

Instale o servidor MCP

Como instalar o servidor MCP Extentos (@extentos/mcp-server) em qualquer agente de codificação de IA compatível com MCP — Claude Code, Cursor, Windsurf, Cline e outros. Comandos de instalação por host, locais de arquivos de configuração, trechos JSON copiáveis, etapas de reinicialização e verificação, fixação de versão, atualização, solução de erros comuns e instruções de desinstalação. Caminhos de instalação verificados para cada host suportado.

](https://extentos.com/docs/mcp-server/install)