Quickstart with an AI agent

Extentos is the smart-glasses infrastructure layer for native mobile apps. An AI coding agent installs the Extentos MCP server, the server exposes a tight set of deterministic tools (capability discovery, code-example reference, project scaffold, validation, browser simulator), and the agent uses them to wire a typed Kotlin/Swift SDK into an existing iOS or Android app — your handler classes then subscribe to primitives like glasses.audio.transcriptions(), glasses.camera.capturePhoto(), and glasses.audio.speak(). Targets Meta Ray-Ban (GA), with other vendors on the roadmap. A browser-based simulator covers the bulk of the dev loop without physical glasses.

This page is the agent-driven path. If you're integrating by hand, see the iOS or Android quickstart instead.

Install

There's no single host-agnostic install command — every MCP host (Claude Code, Cursor, Windsurf, Cline) stores its server config differently. Three paths, in order of recommended:

1. Agent prompt (recommended, host-agnostic)

Open your MCP-capable agent and paste:

Install @extentos/mcp-server in my MCP config.

The agent runs the right command for its host (claude mcp add ... for Claude Code, or edits mcp.json for Cursor / Windsurf / Cline). Restart the agent when it reports done. The Extentos tools appear in the agent's tool list.

2. Claude Code one-liner

If you're on Claude Code and prefer a shell command:

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

Restart Claude Code. Run /mcp — you should see extentos listed with the full tool surface.

3. Manual JSON

For any MCP host, drop this into the host's MCP config file (~/.cursor/mcp.json for Cursor, ~/.codeium/windsurf/mcp_config.json for Windsurf, or equivalent):

{
  "mcpServers": {
    "extentos": {
      "command": "npx",
      "args": ["-y", "@extentos/mcp-server@latest"]
    }
  }
}

Restart the host. The Extentos tools should appear in the agent's tool list.

Prerequisites: Node.js 20 or newer on PATH. That's the only requirement — npx fetches and caches the package on first run.

Pinning a version (optional): Replace @latest with @0.0.56 (current published version) if you need a reproducible install across sessions. Extentos is pre-1.0; APIs may shift between minor versions until the hardware test loop closes.

First prompt to your agent

After install, ask the agent to do the actual work. Two prompt patterns that work well:

Add Extentos smart-glasses voice triggers to my Android app.
The user should be able to say "summarize this" while wearing
Meta Ray-Ban glasses, and the app should run my existing
summarize() function on whatever the camera sees.

Use the Extentos MCP server to add photo capture from
Meta Ray-Ban to my iOS app. When the user double-taps the
glasses, capture a frame, send it to my analyzeImage()
function, and speak the result back.

Be specific about: which platform, which capability (voice / photo / video / sensor / audio), and which existing function in your app should consume the data. The agent composes against the SDK primitives — wake-phrase matching, business logic, error handling — all in plain Kotlin / Swift in a handler class you own.

What the agent does

The MCP server has no planning tool — agents are better planners than regex. The agent composes capability primitives itself, then calls a deterministic sequence. You can watch it happen in the tool log:

For iteration: edit handler code → rebuild + reinstall → the app auto-attaches to the same simulator session. No remint required.

For debugging: getEventLog (filter by errors first to surface every failure across modalities, then narrow to a capability chip — voice / camera / ai / lifecycle / custom), getSimulatorStatus. For ship-readiness: getProductionChecklist. For credentials (BYOK providers + Meta DAT registration): getCredentialGuide.

The full tool reference is at /docs/mcp-server/tools.

Verifying it worked

When the agent calls createSimulatorSession, the MCP server auto-opens a browser tab to your session at extentos.com/s (specifically extentos.com/s/<sessionId>). You should see:

• A glasses surrogate with camera + mic permission prompts (browser-side; no physical hardware)
• A live event log showing your app initializing, the connection opening, and your trigger firing when you exercise it
• A WebSocket-synced view of your app's responses, exactly as they'd appear on real Meta Ray-Ban glasses

Auto-bind is shipped on both Android and iOS: once the Extentos library is in your app, the MCP and library coordinate via a 127.0.0.1:31337/whoami localhost bridge. Subsequent createSimulatorSession calls auto-attach the running app to the new session — no rebuild, no URL paste.

Pricing — Extentos is free

There is no paid tier. Specifically:

Why account-required for the simulator? The browser simulator runs on Extentos's backend (WebSocket hub, voice proxy, event log persistence) — that's the one piece that costs us per-session compute. Asking for a free email-only account is the lightest possible gate. Every other Extentos surface (MCP tools, code generation, validation, on-device sim, real hardware) doesn't touch the backend and stays free without an account.

Account linking happens through the device-code flow: the first createSimulatorSession call returns auth_required with a verification URL, your agent surfaces it, you sign in (Google one-click or email + password + ToS acceptance), and the original tool call retries automatically. No manual token paste, no payment.

Real hardware testing (running your app on actual Meta Ray-Ban glasses) requires your own Meta Developer Center registration — a one-time, free, ~15–30 minute setup using your personal Meta credentials. No Extentos account required for this path.

Full pricing details: /docs/resources/pricing.

Multi-platform projects (Android + iOS = one project)

Your Android and iOS versions share one project on the dashboard — if your Android applicationId (in app/build.gradle.kts) matches your iOS bundle identifier (in your Xcode project). E.g. both set to com.example.myapp. This is the standard reverse-DNS convention; most projects already follow it.

When the identifiers match, minting a simulator from each platform automatically joins the same project — one card on the dashboard, two platform chips, no manual setup. When they don't match, two separate projects appear; you can either align the identifiers in your source or use the dashboard's Merge action (Settings → Danger Zone) to consolidate.

The full story — how project identity is derived, what's preserved across a Merge, what the Settings page surfaces — lives at /docs/concepts/projects.

What's actually supported (be honest with your agent)

The Meta DAT public toolkit is the substrate Extentos sits on. It has real boundaries — your agent should know them so it generates apps that actually run:

• Strong public capabilities: photo capture, video capture, camera streams, sensor data
• Voice triggers: custom phrases work via the phone's speech recognizer over Bluetooth (HFP/SCO). Meta AI's "Hey Meta" wake word is not accessible to third-party apps
• Audio I/O: mic capture and TTS playback ride mobile-platform Bluetooth profiles. Extentos wires the audio session; your platform's native STT/TTS does the work (zero Extentos runtime cost)
• Not available: custom gestures (tap, swipe, swipe-to-confirm) are not in the public toolkit preview
• Distribution: publishing to the Meta App Store is preview-limited. Private testing and Android/iOS export are the safe defaults

See /docs/concepts/capabilities for the full matrix, and /docs/concepts/transport-vs-app for the framing of what Meta provides vs what Extentos adds.

Troubleshooting first-run issues

/mcp doesn't list extentos in Claude Code. Restart Claude Code completely (Cmd+Q / quit from system tray, not just close window). The MCP host loads servers at startup.

npx errors with "command not found". Install Node.js 20 or newer from nodejs.org. Verify with node -v.

The agent's first tool call is slow or times out. npx is fetching the package on first run — wait 10–30 seconds and retry. Subsequent calls hit the cache and are instant.

createSimulatorSession returns authRequired immediately. That's the expected flow on first run — the browser simulator requires a free account. The response includes a verification URL; open it, sign in (Google one-click or email), and the agent retries automatically.

Auto-bind not connecting on Android. Check that nothing else is bound to localhost port 31337. The library logs a warning if the bridge fails to start; falls back to URL-paste mode.

iOS app not picking up the session. Check that nothing else is bound to localhost port 31337; the library logs a warning if the bridge fails to start. Falls back to URL-bake (extentos.session.plist) if the probe times out.

More: /docs/troubleshooting.

Next steps

• MCP server reference — full tool catalog, configuration, auth model
• Concepts: architecture — how the MCP, the library, the simulator, and your app fit together
• Concepts: transport vs app simulation — what Meta provides, what Extentos adds, and why both matter
• Guides — task-shaped recipes (voice triggers, photo capture, sensor streams, background sessions)
• Vendors: Meta Ray-Ban — the GA target and its capability matrix

Status

Pre-1.0 (current: @extentos/mcp-server@0.0.56). Android primary, iOS supported via SPM. APIs may shift between minor versions until the hardware test loop closes — pin to an exact version if you need cross-session reproducibility. Source: github.com/Asgermolgaard/vibe-hardware. License: MIT.