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 18 deterministic tools (discovery, scaffold, validate, simulate), and the agent uses them to add voice triggers, photo capture, and sensor streams to an existing iOS or Android app — targeting 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 all 18 tools.

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.16 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 maps your prose to a spec and generates the bridging code.

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 mutation sequence. You can watch it happen in the tool log:

For iteration: inspectIntegration (for the freshness token) → updateSpec → generateConsumer (if handlers/streams added) → validateIntegration.

For debugging: getEventLog, getSimulatorStatus. For ship-readiness: getProductionChecklist. For studying complex compositions: getExampleSpec returns 8 worked patterns (voice assistant, live translation, video call, etc.).

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

On Android, auto-bind is fully shipped: 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.

On iOS, auto-bind is in progress; the iOS SDK currently uses the URL-bake path via extentos.session.plist until that lands.

Pricing — Extentos is free

There is no paid tier at launch. Specifically:

A "runtime event" is an event emitted by the browser simulator during a session — trigger.fired, block.executed, callback.invoked, etc. A typical voice-to-AI interaction emits 5–10 events, so 1000 events ≈ 100–200 full interactions, roughly enough to validate a non-trivial spec on your actual app. MCP-server-side activity (tool calls, code generation) does not count against the meter, ever.

Account linking is lazy: the device-code flow only fires when you exhaust the 1000-event meter. Your agent gets an authRequired response with a verification URL, opens it in your browser, you sign up with email + ToS acceptance, and the original createSimulatorSession call retries automatically. No manual token paste, no upfront signup wall.

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.

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. You've already used your 1000 free events on this install. The response includes a verification URL — open it, sign up with email (no payment), and the agent will retry 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. iOS auto-bind is in progress. Until it lands, copy the simulator URL from the agent's tool response and bake it into extentos.session.plist — see /docs/sdk/ios for the manual flow.

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.16). 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.