Extentos MCP

MCP 서버

Extentos MCP 서버(@extentos/mcp-server\)는 AI 에이전트(Claude Code, Cursor, Windsurf, Cline)가 한 번 설치한 후 네이티브 iOS 또는 Android 앱에 Meta Ray-Ban 스마트 글래스 기능을 추가하기 위해 사용하는 npm 패키지입니다. 이 서버는 10개 카테고리(발견, 생성, 에이전트 구성, 자격 증명, 분석, 가이드, 검증, 시뮬레이션, 프로덕션 준비, 문서화)에 걸쳐 결정적인 도구 집합을 노출하며, 계정 연결, 원격 측정 동의, 업데이트 확인을 위한 CLI도 포함합니다. 이것이 에이전트의 운영 매뉴얼입니다.

MCP 서버는 AI 에이전트(Claude Code, Cursor, Windsurf, Cline 또는 Model Context Protocol 호환 호스트)가 Extentos를 운영하는 방식입니다. 에이전트는 결정적인 도구를 호출하고, 서버는 글래스가 노출하는 기능에 대해 에이전트를 사전 안내하며, Kotlin 및 Swift의 표준 SDK 코드 패턴을 반환하고, 프로젝트를 스캐폴딩하며, 시뮬레이터 세션을 중개하고, 디버깅 추적을 조회합니다. 서버 자체에는 계획 도구가 없습니다 — 에이전트가 정규식 번들보다 더 나은 계획자입니다. 도구는 에이전트가 순서대로 구성하는 타입화된 기본 요소입니다.

이 페이지는 섹션 랜딩 페이지입니다 — 서버가 무엇인지, 도구 개요, 표준 에이전트 주도 흐름, 구성 옵션, CLI, 인증 모델 작동 방식. 하위 페이지에서 각 항목을 자세히 다룹니다.

설치

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

Claude Code가 아닌 호스트의 경우 에이전트 프롬프트 또는 수동 JSON 설치 경로를 참조하세요. 전체 설치 참조는 /docs/mcp-server/install에 있습니다.

카테고리별 도구

서버는 10개 카테고리로 구성된 결정적인 도구 표면을 노출합니다(mcp-server/src/tools/definitions.ts에서 검증됨). 카테고리는 에이전트의 정신적 지도입니다. 도구가 속한 카테고리를 이해하는 에이전트는 언제 호출할지 결정할 수 있습니다. 항상 최신의 전체 카탈로그는 생성된 도구 참조에 있습니다.

1. 발견 및 SDK 참조 (4개 도구)

새 작업에서 첫 번째 호출. 저렴하고, 모두 로컬이며, 부작용이 없습니다.

도구	기능
getPlatformInfo	정적 플랫폼 카탈로그 반환 — 라이브러리 버전, 글래스가 노출하는 SDK 기능 목록, 공급업체별 등급. 항상 올바른 첫 호출입니다.
getCapabilityGuide	Kotlin + Swift의 기능별 최소 사용법 — 호출 형태, 구성 인수, 주의 사항. getPlatformInfo(기능 이름 지정)과 함께 사용하여 에이전트가 각 기능을 호출하는 방법을 알려줍니다.
getCodeExample	두 언어의 전체 표준 구성. assistant_agent_loop(Phase-4 표준 음성 어시스턴트 흐름) 및 agent_driven_e2e_full_loop(에이전트 주도 E2E 테스트)로 시작하세요. 또한 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, video_frames_ml을 다룹니다. 핸들러 코드 작성 시 여기서 참조하세요. 전체 열거 목록은 /docs/reference/mcp-tools에서 생성됩니다.
getMigrationGuide	원시 Meta DAT 위에 이미 구축된 앱용 — 기존 DAT 심볼을 대체하는 Extentos 기본 요소에 대한 맵과 순서가 지정된 전환 계획을 반환합니다.

2. 설정 및 생성

도구	기능
generateConnectionModule	원샷 스캐폴드 — 부트스트랩 모듈, Gradle/SPM 연결, 종속성, 권한, 매니페스트. 두 번 호출 흐름: placement 없이 첫 번째 호출은 ExtentosConnectionPage가 위치해야 할 위치를 묻는 질문을 반환하고, 선택한 배치로 두 번째 호출은 전체 파일 세트를 반환합니다.
getConnectionPageConfig / setConnectionPageConfig	대시보드/서버가 보유한 프로젝트별 연결 페이지 구성(테마 토큰 + 섹션 가시성) 읽기/쓰기.
regenerateConnectionPageFile / adoptConnectionPageFile	커밋된 extentos.connection-page.json을 서버 구성과 동기화 — 재생성(서버→파일) 또는 채택(파일→서버).

스캐폴딩 후 에이전트는 getCapabilityGuide / getCodeExample가 표면화한 SDK 기본 요소에 대해 자체 핸들러 클래스를 작성합니다. 핸들러 코드는 고객의 작성 표면입니다 — initSpec 또는 DSL 채우기 단계가 없습니다.

3. 에이전트 구성 및 사용 (5개 도구)

계정 범위 — 연결된 계정이 필요하며 MCP 액세스 권한(기본 읽기+쓰기)으로 프로젝트별 게이트됩니다.

도구	기능
getAssistantConfig / setAssistantConfig	프로젝트의 대시보드 관리 어시스턴트 설정 읽기 또는 변경 — OpenAI Realtime 모델, 음성, 메모리(압축) 모델, 세션 내 메모리 모드. set은 부분 업데이트이며 각 값을 카탈로그에 대해 검증하고 모델 변경의 비용 영향을 에코합니다.
getGatewayUsage	최근 기간 동안 프로젝트의 관리 게이트웨이 사용량 + 정확한 비용 읽기 — 청구 원장의 토큰 수 및 목록 가격 USD, 모델별 분류. 메타데이터만, 전사 또는 콘텐츠는 절대 없음.

4. 자격 증명 (2개 도구)

계정 범위 + 프로젝트별 게이트. 알지 못한 채 쓰기 — 비밀은 에이전트를 통과하지 않습니다.

도구	기능
getCredentialStatus	프로젝트의 Meta DAT 빌드 ID가 설정되었는지 읽기 — 마스킹된 힌트 + 업데이트 시간만, 값은 절대 없음.
setCredential	자격 증명의 알지 못한 채 쓰기 입력 시작 — 로그인한 소유자가 암호화된 볼트에 비밀을 직접 붙여넣는 대시보드 링크 반환. 설계상 비밀 인수를 받지 않습니다.

5. 분석 (1개 도구)

도구	기능
getProjectAnalytics	프로젝트의 프로덕션 분석 읽기 — 출시된 App Store / Play Store 설치의 집계 원격 측정(이벤트, 활성 설치, 이벤트/일/공급업체/플랫폼별). 메타데이터만, 계정 범위, 소유권 확인, 분석 권한으로 게이트. 앱이 출시되고 프로덕션 증명 이벤트를 보낼 때까지 비어 있음(라이브 개발/시뮬레이터 스트림에는 getEventLog 사용).

6. 구현 가이드 (2개 도구)

구성 중 에이전트가 호출하는 사이드 퀘스트 도구.

도구	기능
getVoiceCommandGuidance	제안된 웨이크/명령 문구를 UX 문제(충돌, 모호성, 인식 어려운 단어, Meta 웨이크 단어 충돌)에 대해 분석한 후 glasses.audio.transcriptions() 소비자에 연결.
getPermissions	기능 목록에서 정확한 플랫폼 권한, Meta DAT 요구 사항, 포그라운드 서비스 필요성을 도출. 핸들러에서 기본 요소를 추가하거나 제거할 때 실행.

7. 검증 (2개 도구)

정확성 게이트. 구조적 변경(새 기능 선언, 종속성 범프, 매니페스트 편집) 후 실행.

도구	기능
inspectIntegration	읽기 전용 프로젝트 스냅샷 — 매니페스트, 생성 파일 해시, 종속성 목록, 연결 페이지 구성. 수동 편집 전에 현재 상태를 이해하기 위해 실행.
validateIntegration	전체 프로젝트 정확성 검사 — 매니페스트, 생성 파일, 선언된 종속성, 선언된 기능을 포함하는 권한, 부트스트랩이 ExtentosGlasses.create(...) 호출, 도구 체인 버전, 연속 캡처 흐름에 대한 포그라운드 서비스 힌트. 사전 테스트 게이트.

8. 시뮬레이션

브라우저 기반 시뮬레이터 세션 프로비저닝 및 운영, 인간 없이 엔드투엔드 루프를 닫는 에이전트 주도 테스트 도구.

도구	기능
createSimulatorSession	extentos.com/s에서 브라우저 모드 세션 가져오기 또는 생성. 이 프로젝트에 저장된 시뮬레이션이 있으면 반환(status: "resumed"), 없으면 새로 생성(status: "active"). 로컬 브리지를 통해 실행 중인 앱을 자동 연결 가능하면 연결, 그렇지 않으면 BuildConfig.EXTENTOS_SESSION_URL 스니펫(Android) 또는 extentos.session.plist 페이로드(iOS)를 방출. sessionId 회전은 deleteSimulatorSession 후 생성 — 강제 새로 고침 플래그가 없습니다.
ensureSimulatorBrowser	연결된 시뮬레이터 브라우저 탭 열기 + 확인 — 카메라 및 주입 흐름의 전제 조건.
completeAuthLink	createSimulatorSession이 status: "auth_required"을 반환한 후(익명 설치가 세션 생성에 연결해야 함), 사용자가 가입을 완료할 때까지 백엔드를 폴링한 다음 베어러 토큰을 ~/.extentos/auth.json에 유지.
getEventLog	세션에서 구조화된 이벤트 추적 가져오기. 필터 값: all(필터 없음) + 7개 칩 errors, voice, camera, display, ai, lifecycle, custom — 이벤트당 칩 하나, errors은 양식에 관계없이 심각도≥경고를 흡수. 또한 추적 수준 범위에 cursor, follow, limit. 기본 디버깅 도구.
getSimulatorStatus	라이브 세션의 현재 상태 읽기 — 단계, 하드웨어 준비, 연결된 역할, 활성 기능 스트림, 현재 토글 값.
injectTranscript / injectAssistantUtterance / assertToolCalled	웨이크 문구 또는 어시스턴트 턴을 구동한 다음 모델이 호출한 도구를 어설션 — 인간 없이 에이전트 주도 E2E 루프.
injectHardwareButton	시뮬레이션된 글래스의 하드웨어 캡처 버튼 누르기 — 탭은 라이브 카메라 스트림을 일시 중지/재개, 길게 누르기는 중지 — 에이전트가 착용자의 개인정보 제스처를 인간 없이 실행(및 결과 CaptureError.StreamPaused 테스트)할 수 있음.
setSimVideo / setSimDevice	테스트 비디오를 시뮬레이션된 카메라에 파이프; 시뮬레이션된 장치 모델 전환(예: rayban_display으로 디스플레이 경로 실행).
getDisplayState / injectInput	현재 렌더링된 디스플레이 트리 읽기 + 디스플레이 입력 구동(select / navigate / back).

9. 프로덕션 (2개 도구)

출시 전 검사.

도구	기능
getProductionChecklist	선언된 기능 + 핸들러 이름 기반 개인화된 프로덕션 준비 체크리스트 — 자격 증명 연결, 권한 감사, 포그라운드 서비스 요구 사항(연속 캡처 사용 시), 릴리스 빌드에서 시뮬레이터 URL 제거, 스토어 목록 준비.
getCredentialGuide	프로덕션 AI 공급자에 대한 단계별 자격 증명 설정 — anthropic, openai, google_cloud_vision, google_translate, google_gemini, deepl, azure_cognitive, aws_bedrock, huggingface 또는 custom — 및 Meta DAT 등록.

10. 문서 및 검색 (1개 도구)

도구	기능
searchDocs	주제 또는 키워드로 Extentos 문서 검색. 음성 어시스턴트의 경우 assistant_runtime를 먼저 읽으세요. 기타 관련 주제: voice_integration, agent_e2e_testing, managed_gateway, conversation_memory, display, 및 안정적인 개념 세트 — getting_started, custom_handlers(표준 SDK 구성 문서), simulator_browser_mode, simulator_session_lifecycle, event_log_schema, toggles, library_api, permissions, multi_platform_projects. 주제 ID는 안정적이며 라이브 도구 입력이 권위 있습니다.

입력 스키마, 응답 형태, 작업 예제가 포함된 전체 도구별 참조: /docs/mcp-server/tools.

표준 에이전트 주도 흐름

새 프로젝트에서 에이전트는 다음 순서로 도구를 호출합니다:

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

반복의 경우: 핸들러 코드 편집 → 재빌드 + 재설치 → 앱이 동일한 시뮬레이터 세션에 자동 연결(재생성 없음, URL은 안정적). 출시 전: getProductionChecklist 및 getCredentialGuide.

구성

MCP 서버는 다음 환경 변수를 읽습니다(mcp-server/src/에서 검증됨):

변수	기본값	기능
EXTENTOS_BACKEND_URL	프로덕션 백엔드	백엔드 URL 재정의(tools/util/backendClient.ts). Extentos 자체의 로컬 개발용.
EXTENTOS_CONFIG_DIR	~/.extentos	구성/인증 디렉터리 재정의(telemetry/consent.ts).
EXTENTOS_TELEMETRY	설정되지 않음(동의 기본값)	0으로 설정하여 CLI 동의 명령 없이 원격 측정 거부.
EXTENTOS_NO_AUTO_OPEN	설정되지 않음	1으로 설정하여 시뮬레이터 세션 생성 시 브라우저 자동 열기 비활성화(헤드리스 환경에서 유용).

전체 구성 참조: /docs/mcp-server/configuration.

CLI 하위 명령

Running npx @extentos/mcp-server@latest with no arguments starts the MCP server over stdio (the path the agent uses). With a subcommand, it acts as a developer CLI:

Subcommand	What it does
login	Link this install to an Extentos account via device-code flow (proactive — useful before the first simulator session, or after logout to re-link).
logout	Clear ~/.extentos/auth.json. Install returns to the anonymous tier; the next simulator session call will re-trigger the device-code flow.
whoami	Not yet implemented (Phase-0 stub). Will print installId, accountId (if linked), tier, auth expiry.
setup	Preflight the local build environment — checks the GitHub Packages PAT (read:packages) the Meta DAT artifacts need, for apps that depend on com.extentos:glasses-meta, plus other dependency prerequisites.
accept-privacy	Record privacy consent (enables telemetry upload).
decline-privacy	Record privacy decline (disables telemetry upload).
status	Print consent state, install ID, linked account, MCP/library versions.
update	Check for MCP server updates (no-op on npx @latest installs).

Full CLI reference: /docs/mcp-server/auth.

Auth model

The MCP server is anonymous-first. Discovery, capability guides, code examples, validation, docs search, on-device simulation, and real-hardware testing all work without ever signing in. Three things link a free account: minting browser-simulator sessions (createSimulatorSession, HTTP 402), the generateConnectionModule scaffold step (it mints your account-bound project key — same 402 device-code flow; the informational first call is anonymous), and the account-scoped project tools (assistant config, credentials, connection-page writes, analytics — HTTP 401).

The device-code flow: the first gated call returns status: "auth_required" with a verification URL. The agent calls completeAuthLink to poll the backend; the developer signs up with a free email-only account at the URL (Google or email + password, no payment); the backend issues a token; the original tool call retries automatically. After linking, simulator sessions are unlimited.

Extentos's tools, codegen, validation, SDK, and the browser simulator are free — there's no per-seat or subscription fee to build and ship. The one surface that meters usage is the managed AI gateway behind the Phase-4 voice assistant. Full auth model: /docs/mcp-server/auth; pricing: /docs/resources/pricing.

Privacy and telemetry

On first run, the MCP server injects a one-time privacy notice into the response. Telemetry is anonymous (tagged with installId, no source code or personal data) and is dismissed-by-continuing by default — same pattern as Vercel CLI, Astro, Vite. Decline at any time:

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

Privacy notice content is in mcp-server/src/index.ts (PRIVACY_NOTICE constant). Notice is shown once per install via claimFirstPrivacyNotice — never repeats.

Compatible MCP hosts

Verified to work with:

• Claude Code — primary target. One-line install via claude mcp add.
• Cursor — JSON config in ~/.cursor/mcp.json.
• Windsurf — JSON config in ~/.codeium/windsurf/mcp_config.json.
• Cline — JSON config in Cline's MCP settings.
• Any MCP-compatible host — drop the standard mcpServers.extentos JSON block in.

The MCP server speaks the standard MCP protocol over stdio (@modelcontextprotocol/sdk); no host-specific code paths exist on the server side. Per-host install steps: /docs/mcp-server/agents.

The local bridge — auto-bind dev loop

When the server starts, it opens a 127.0.0.1:31337/whoami HTTP listener (mcp-server/src/localBridge.ts). The Extentos library on the developer's app probes this endpoint at runtime to learn its host MCP's installId. The result: every createSimulatorSession call from the agent auto-attaches the running app to the new session — no rebuild, no URL paste.

Reach paths:

• Android emulator: http://10.0.2.2:31337/whoami (host-loopback NAT alias)
• iOS Simulator: http://localhost:31337/whoami (shares host network namespace)
• Physical Android phone via USB: adb reverse tcp:31337 tcp:31337 once, then localhost:31337 from the device
• Cellular phone or cloud-hosted agent: probe times out. The agent uses the URL-bake path instead — createSimulatorSession returns a BuildConfig.EXTENTOS_SESSION_URL snippet (Android) or extentos.session.plist payload (iOS) the developer pastes in, then rebuilds the app once. Less elegant than auto-bind but works on any topology.

Bound to 127.0.0.1 only. The installId is not a secret — it's the same value the MCP sends to api.extentos.com on every tool call. No auth needed at this layer.

If port 31337 is in use (rare; another MCP instance already running), startup logs a warning and continues. Auto-bind silently fails for that session; the developer uses the URL-bake path until the port frees up.

Status

• Package: @extentos/mcp-server on npm (MIT license)
• Engines: Node.js 20+
• Pre-1.0 — APIs may shift between minor versions until the hardware test loop closes. Pin to an exact version if you need cross-session reproducibility.

Related

• Quickstart with an AI agent — install the server and walk through a real dev loop
• Tools reference — full per-tool API
• Configuration — environment variables, config files, install-time settings
• Auth — device-code flow, account linking, CLI auth commands
• Supported agents — per-host install instructions
• Architecture — how the MCP server fits into the broader Extentos system
• Transport vs app simulation — what the simulator the MCP brokers actually does

[

Alibaba Qianwen AI Glasses

Alibaba Qianwen AI Glasses for third-party developers — the 千问AI硬件开放平台 Skill platform, MCP tool integration, app model, distribution, capabilities & AI, and where it sits in the 2026 smart-glasses landscape.

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

Install the MCP server

How to install the Extentos MCP server (@extentos/mcp-server) in any MCP-compatible AI coding agent — Claude Code, Cursor, Windsurf, Cline, and others. Per-host install commands, config file locations, copy-pasteable JSON snippets, restart and verify steps, version pinning, updating, troubleshooting common errors, and uninstall instructions. Verified install paths for each supported host.

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