Extentos MCP

Servidor MCP

Servidor MCP

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 dos óculos inteligentes Meta Ray-Ban a um app nativo iOS ou Android. Ele expõe um conjunto enxuto de ferramentas determinísticas em 10 categorias — descoberta, geração, configuração do agente, credenciais, análises, 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 de operação do agente.

O servidor MCP é como um agente de IA — Claude Code, Cursor, Windsurf, Cline ou qualquer host compatível com o Model Context Protocol — opera o 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, intermedeia sessões do simulador e consulta rastros de depuração. O servidor em si não possui ferramenta de planejamento — agentes são melhores planejadores do que conjuntos de regex. As ferramentas são primitivas tipadas que o agente compõe em sequência.

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

Instalar

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

Para hosts que não sejam o Claude Code, consulte o prompt do agente ou os caminhos de instalação manual via JSON. 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 a qual categoria uma ferramenta pertence pode decidir quando chamá-la. O catálogo completo sempre atualizado é a referência de ferramentas gerada.

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

As primeiras chamadas em qualquer nova tarefa. Rápidas, 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 do SDK que os óculos expõem, níveis por fornecedor. Sempre a primeira chamada correta.
getCapabilityGuide	Uso mínimo por funcionalidade em Kotlin + Swift — formato da chamada, argumentos de configuração, pontos de atenção. Complementa getPlatformInfo (que nomeia as funcionalidades) para informar ao agente como invocar cada uma.
getCodeExample	Composições canônicas completas em ambas as linguagens. 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 manipulador. A lista completa enumerada é gerada em /docs/reference/mcp-tools.
getMigrationGuide	Para apps já construídos sobre o Meta DAT bruto — retorna um mapa indexado pelos seus símbolos DAT existentes para as primitivas Extentos que os substituem, além de um plano de transição ordenado.

2. Configuração e Geração

Ferramenta	O que faz
generateConnectionModule	Estruturação única — inicializa módulo, configuração Gradle/SPM, dependências, permissões, manifesto. Fluxo de duas chamadas: a primeira chamada sem posicionamento retorna uma pergunta sobre onde ExtentosConnectionPage deve residir; a segunda chamada com o posicionamento escolhido retorna o conjunto completo de arquivos.
getConnectionPageConfig / setConnectionPageConfig	Lê / grava a configuração da página de conexão por projeto (tokens de tema + visibilidade da seção) mantida pelo painel/servidor.
regenerateConnectionPageFile / adoptConnectionPageFile	Sincroniza o arquivo extentos.connection-page.json versionado 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 manipulador com base nas primitivas do SDK expostas por getCapabilityGuide / getCodeExample. O código do manipulador é 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)

Com escopo de conta — requerem uma conta vinculada e são controladas por projeto pela concessão de acesso MCP (padrão Leitura+Escrita).

Ferramenta	O que faz
getAssistantConfig / setAssistantConfig	Lê ou altera as configurações do 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 no custo de uma mudança de modelo.
listProjectSounds / addProjectSound	Lista ou envia a biblioteca de sons nomeados de um projeto — arquivos MP3/M4A/AAC/WAV com menos de 1 MB que o código do app reproduz com glasses.audio.playSound(name) (iOS hoje; a reprodução no Android está a caminho) — o painel também pode escolher um como som de despertar. Controlado pela concessão assistant_config.sounds.
getGatewayUsage	Lê o uso do gateway gerenciado do projeto + custo exato em uma janela recente — contagens de tokens e USD de preço de tabela do livro-razão de cobrança, discriminados por modelo. Apenas metadados, nunca transcrições ou conteúdo.

4. Credenciais (2 ferramentas)

Com escopo de conta + controladas por projeto. Gravar sem saber — o segredo nunca passa pelo agente.

Ferramenta	O que faz
getCredentialStatus	Lê se a chave de API OpenAI (BYOK) e a identidade de build Meta DAT de um projeto estão definidas — uma dica mascarada + atualizado em apenas, nunca o valor.
setCredential	Inicia a entrada de credencial no modo gravar sem saber — retorna um link do painel onde o proprietário autenticado cola o segredo diretamente no cofre criptografado. Não aceita argumento de segredo por design.

5. Análises (1 ferramenta)

Ferramenta

O que faz

getProjectAnalytics

Lê as análises de produção de um projeto — telemetria agregada de instalações enviadas pela App Store / Play Store (eventos, instalações ativas, por evento / dia / fornecedor / plataforma). Apenas metadados, com escopo de conta, verificação de propriedade, controlado pela concessão Analytics. Vazio até que o app seja enviado e envie 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 ela faz
getVoiceCommandGuidance	Analisa frases de despertar/comando propostas em busca de problemas de UX (colisões, ambiguidade, palavras difíceis de reconhecer, conflitos com palavras de despertar da Meta) antes de conectá-las a um consumidor glasses.audio.transcriptions().
getPermissions	Deriva permissões exatas da plataforma, requisitos do 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 manipulador.

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 ela faz
inspectIntegration	Instantâneo do projeto somente leitura — 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 de todo o projeto — manifesto, arquivos gerados, dependência declarada, permissões cobrem capacidades declaradas, bootstrap chama ExtentosGlasses.create(...), versões do 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 ciclo ponta a ponta sem um humano.

Ferramenta	O que ela faz
createSimulatorSession	Obtém ou cria uma sessão em modo navegador em extentos.com/s. Retorna a simulação salva para este projeto, se existir (status: "resumed"), ou cria uma nova (status: "active"). Anexa automaticamente o aplicativo em execução via ponte local quando acessível; caso contrário, emite um snippet BuildConfig.EXTENTOS_SESSION_URL (Android) ou payload extentos.session.plist (iOS). Passe resetFresh: true para rotacionar o sessionId e começar do zero.
ensureSimulatorBrowser	Abre + confirma uma aba do navegador do 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é que o usuário finalize o cadastro e então persiste o token de portador em ~/.extentos/auth.json.
getEventLog	Busca 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≥warn independentemente da modalidade. Mais cursor, follow, limit para escopo em nível de rastro. A ferramenta de depuração primária.
getSimulatorStatus	Lê o estado atual de uma sessão ao vivo — fase, hardware pronto, funções anexadas, fluxos de capacidade ativos, valores atuais de alternância.
injectTranscript / injectAssistantUtterance / assertToolCalled	Aciona uma frase de despertar ou um turno do assistente e, em seguida, verifica qual ferramenta o modelo chamou — o ciclo E2E orientado por agente, sem necessidade de humano.
injectHardwareButton	Pressiona o botão de captura de hardware dos óculos simulados — tocar 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 um humano.
setSimVideo / setSimDevice	Insere um vídeo de teste na câmera simulada; alterna o modelo de dispositivo simulado (ex.: rayban_display para exercitar o caminho de exibição).
getDisplayState / injectInput	Lê a árvore de exibição atualmente renderizada + aciona entrada de exibição (selecionar / navegar / voltar).

9. Produção (2 ferramentas)

Verificações pré-envio.

Ferramenta	O que ela faz
getProductionChecklist	Checklist de prontidão para produção personalizado com base nas capacidades declaradas + nomes de manipuladores — conexão de credenciais, auditoria de permissão, requisitos de serviço em primeiro plano (quando captura contínua é usada), remoção de URL do simulador de builds de release, prontidão para listagem na loja.
getCredentialGuide	Configuração passo a passo de credenciais para provedores de IA de produção — anthropic, openai, google_cloud_vision, google_translate, google_gemini, deepl, azure_cognitive, aws_bedrock, huggingface ou custom — mais registro no Meta DAT.

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

Ferramenta

O que ela faz

searchDocs

Busca na documentação do Extentos por tópico ou palavra-chave. Para assistentes de voz, leia assistant_runtime primeiro; conversation_runtime é o runtime obsoleto da Fase 3 (apenas referência de migração). Outros tópicos alinhados: voice_integration, agent_e2e_testing, managed_gateway, conversation_memory, display, mais o conjunto conceitual estável — getting_started, custom_handlers (o documento canônico de composição do SDK), simulator_browser_mode, event_log_schema, toggles, library_api, permissions, multi_platform_projects. Os IDs de tópico são estáveis; a entrada da ferramenta ao vivo é autoritativa.

Referência completa por ferramenta com esquemas de entrada, formatos de resposta e exemplos práticos: /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 manipulador → reconstrua + reinstale → o aplicativo se anexa automaticamente à mesma sessão do simulador (sem recriação, a URL é estável). Antes de enviar: 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	Substitui a URL do backend (tools/util/backendClient.ts). Para desenvolvimento local do próprio Extentos.
EXTENTOS_CONFIG_DIR	~/.extentos	Substitui o diretório de configuração/auth (telemetry/consent.ts).
EXTENTOS_TELEMETRY	não definida (consentimento padrão)	Defina como 0 para recusar telemetria sem executar o comando de consentimento da CLI.
EXTENTOS_NO_AUTO_OPEN	não definida	Defina como 1 para desabilitar a abertura automática do navegador ao criar uma sessão do 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 revincular).
logout	Limpa ~/.extentos/auth.json. A instalação retorna ao nível anônimo; a próxima chamada de sessão do simulador reativará o fluxo de código de dispositivo.
whoami	Ainda não implementado (esboço da Fase 0). Exibirá installId, accountId (se vinculado), nível, expiração da autenticação.
setup	Prepara o ambiente de build local — verifica o PAT do GitHub Packages (read:packages) necessário para os artefatos transitivos do Meta DAT, além de outros pré-requisitos de dependência.
accept-privacy	Registra o consentimento de privacidade (habilita o envio de telemetria).
decline-privacy	Registra a recusa de privacidade (desabilita o envio de telemetria).
status	Exibe o estado do consentimento, ID da instalação, conta vinculada, versões do MCP/biblioteca.
update	Verifica atualizações do servidor MCP (sem efeito em instalações npx @latest).

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

Modelo de autenticação

O servidor MCP é anônimo por padrão. Descoberta, guias de capacidade, exemplos de código, validação, busca na 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 scaffolding generateConnectionModule (ela cria 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 de página de conexão, análises — HTTP 401).

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

As ferramentas, geração de código, validação, SDK e o simulador de navegador do Extentos são gratuitos — não há taxa por usuário ou assinatura para construir e distribuir. A única superfície que mede o 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 é exibido 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 definiçõ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 para host no lado do servidor. Etapas de instalação por host: /docs/mcp-server/agents.

A ponte local — ciclo 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 aplicativo do desenvolvedor sonda este endpoint em tempo de execução para descobrir o installId do seu host MCP. O resultado: cada chamada createSimulatorSession do agente anexa automaticamente o aplicativo em execução à nova sessão — sem reconstrução, 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)
• Telefone Android físico via USB: adb reverse tcp:31337 tcp:31337 uma vez, depois localhost:31337 do dispositivo
• Telefone celular ou agente hospedado na nuvem: a sondagem expira. O agente usa o caminho de inclusão de URL — createSimulatorSession retorna um trecho BuildConfig.EXTENTOS_SESSION_URL (Android) ou carga extentos.session.plist (iOS) que o desenvolvedor cola e então reconstrói o aplicativo 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), a inicialização registra um aviso e continua. A auto-vinculação falha silenciosamente para essa sessão; o desenvolvedor usa o caminho de inclusão de URL até que a porta seja liberada.

Status

• Pacote: @extentos/mcp-server no npm (licença MIT)
• Motores: Node.js 20+
• Pré-1.0 — APIs podem mudar entre versões menores até que o ciclo de teste de hardware seja fechado. 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 ciclo de desenvolvimento real
• Referência de ferramentas — API completa por ferramenta
• Configuração — variáveis de ambiente, arquivos de configuração, definições de tempo 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 aplicativo — o que o simulador intermediado pelo MCP realmente faz

Relacionados

Início rápido com um agente de IA

Instale o servidor Extentos MCP e deixe seu agente de IA integrar recursos de smart glasses Meta Ray-Ban em um aplicativo nativo iOS ou Android. Gratuito para começar.

Arquitetura

Como o Extentos se integra — agente de IA, servidor MCP, SDK nativo Kotlin/Swift, três transportes (Meta DAT, simulador de navegador, simulador local em memória) e o backend.

Transporte vs simulação de aplicativo

O Mock Device Kit da Meta simula a camada de transporte; o Extentos simula a camada do aplicativo — voz, captura de foto e a experiência de uso. Ambos são importantes.

Instalar o servidor MCP

Como instalar o servidor Extentos MCP (@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 arquivo de configuração, trechos JSON para copiar e colar, etapas de reinicialização e verificação, fixação de versão, atualização, solução de problemas comuns e instruções de desinstalação. Caminhos de instalação verificados para cada host suportado.

Referência de ferramentas

O servidor Extentos MCP expõe um conjunto enxuto de ferramentas determinísticas em categorias determinísticas — descoberta e referência do SDK, geração, orientação, validação, simulação, produção, configuração do agente e busca. Referência por ferramenta cobrindo parâmetros de entrada, formatos de resposta, quando chamar cada ferramenta e exemplos práticos. Verificado a partir das definições reais de ferramentas e implementações de manipuladores em @extentos/mcp-server.

Configuração

Configure @extentos/mcp-server — variáveis de ambiente, os arquivos de estado ~/.extentos (id de instalação, autenticação, consentimento) e o fornecedor padrão.

Autenticação

Como funciona a autenticação do Extentos. Descoberta, orientação, validação e busca funcionam sem conta; uma conta gratuita (vinculada via fluxo de código de dispositivo OAuth 2.0) desbloqueia sessões do simulador de navegador, a etapa de scaffolding e as ferramentas de projeto com escopo de conta. Sem pagamento.

Agentes suportados

Diferenças por host para agentes de codificação de IA que executam o Extentos — Claude Code, Cursor, Windsurf, Cline, integrados em IDEs. Escopo, alcance multiplataforma, suporte MCP.

Apple smart glasses

Apple smart glasses para desenvolvedores terceiros — acesso ao SDK, modelo de aplicativo, distribuição, capacidades e IA, e onde se situa no cenário de smart glasses de 2026.

Instalar o servidor MCP