Install the MCP server

The Extentos MCP server (@extentos/mcp-server, MIT) is published on npm and installs into any Model Context Protocol-compatible AI coding agent. This page is the per-host install reference — Claude Code, Cursor, Windsurf, Cline, and the generic MCP-host pattern that covers everything else. Each section gives the verified config file path, the exact JSON snippet to paste, the restart-and-verify steps, and links to troubleshooting if it doesn't work the first time.

Before you start

Prerequisites:

• Node.js 20 or newer on PATH. Verify with node -v. The MCP server is published as an npm package and runs through npx; older Node versions will fail with Unsupported engine errors.
• Any MCP-compatible AI coding agent. Claude Code, Cursor, Windsurf, Cline are all officially verified. Any host that speaks the standard MCP protocol over stdio works — see the generic MCP host section.
• No Extentos account needed. All MCP tools work anonymously; the auth flow only fires after the 1000-event browser-simulator meter exhausts.

Three install paths, ranked by simplicity:

1. Agent prompt — paste a sentence into your agent and let it install Extentos using its own filesystem-edit / shell tools. Host-agnostic, recommended.
2. Host-specific command or config — direct install via the host's CLI (Claude Code) or config file (Cursor, Windsurf, Cline). Per-host instructions below.
3. Generic MCP JSON — drop the standard mcpServers block into the host's MCP config file by hand. Universal fallback.

Path 1 — Agent prompt (recommended, host-agnostic)

Paste this into your AI coding agent:

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

The agent will:

• Run the right command (claude mcp add ... for Claude Code) or edit the right config file (~/.cursor/mcp.json for Cursor, etc.)
• Tell you to restart your agent host
• Verify the tools appear after restart

This is the simplest path because the agent figures out the host conventions itself. Use it unless you specifically want to control the install yourself.

Path 2 — Host-specific install

Claude Code

The cleanest install — Claude Code has a native MCP CLI:

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

Restart Claude Code (Cmd+Q on macOS, quit from system tray on Windows / Linux — closing the window isn't enough).

Verify: run /mcp in Claude Code. You should see extentos listed with all 18 tools available. Or claude mcp list from the terminal.

The command writes the server entry to your Claude Code MCP config (typically ~/.claude.json). To remove: claude mcp remove extentos.

Cursor

Cursor uses an mcp.json file. Two scopes:

• Global (all projects): ~/.cursor/mcp.json
• Project-only (this repo): .cursor/mcp.json at the project root

Create or edit the file with:

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

If the file already has other MCP servers, add "extentos" as a sibling key inside mcpServers.

Restart Cursor (full quit, not just close window).

Verify: open Cursor's MCP settings panel — extentos should appear in the server list with a green status indicator and 18 tools. Or ask the agent: "List the MCP servers you have available" — Extentos's tools should be enumerated.

Windsurf

Windsurf uses a JSON config at ~/.codeium/windsurf/mcp_config.json. Create or edit it:

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

Restart Windsurf completely.

Verify: open Windsurf's MCP / tools panel. Extentos should be listed. Or invoke the agent and ask it to call any Extentos tool (e.g., "Run getPlatformInfo for meta_rayban") — it should succeed.

Cline (VS Code extension)

Cline ships as a VS Code extension. Two ways to add the MCP server:

Via Cline's UI (recommended):

1. Open the Cline panel in VS Code
2. Click the MCP Servers tab
3. Click Edit MCP Settings (or Configure MCP Servers depending on Cline version)
4. Paste the JSON below and save:

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

Via the config file directly — cline_mcp_settings.json, typically at:

Restart VS Code (or reload the Cline extension via the command palette: Developer: Reload Window).

Verify: Cline's MCP Servers tab should show extentos with a green status. Tools enumerate when you ask Cline anything Extentos-related.

Generic MCP host

Any host that supports the standard Model Context Protocol can use the same JSON shape. The host's config file path varies, but the server entry is identical:

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

Find your host's MCP config file (consult the host's documentation). Common locations follow the pattern ~/.<host>/mcp*.json or somewhere under ~/.config/<host>/. Drop the mcpServers.extentos entry in, restart, verify.

Pinning a version

By default, @latest resolves to the most recent published version on every npm fetch. For reproducibility across sessions, pin a specific version:

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

Why pin: Extentos is pre-1.0 (current @0.0.16 as of writing). Minor version bumps may shift APIs until the hardware test loop closes. Pinning means a known-good install survives across MCP server restarts even if a new version ships overnight. The tradeoff is missing bug fixes — re-pin to a newer version periodically.

For Claude Code's CLI, pinning looks the same:

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

Updating

If you used @latest, every host restart re-resolves the version through npm — you're always on the newest one as long as your network reaches the npm registry. No manual update step required.

If you pinned a version, edit the config to a newer version number and restart your host. Run npx @extentos/mcp-server@latest update to check whether a newer version exists (no-op on @latest installs).

You can also force a fresh fetch by deleting the npx cache:

# macOS / Linux
rm -rf ~/.npm/_npx

# Windows
rmdir /s "%APPDATA%\npm-cache\_npx"

The next host restart re-downloads the package.

Verifying the install worked

The fastest universal check: ask your agent to call any Extentos tool. For example:

Run getPlatformInfo with sections ["version", "capabilities"] and glasses "meta_rayban"

A successful response includes the library version, the Meta Ray-Ban capability catalog (compact form, ~2 KB), and a summary field. If the agent reports the tool isn't available, the server didn't load — see troubleshooting below.

Per-host verification methods:

The full list of 18 tools you should see: see /docs/mcp-server for the catalog.

Troubleshooting

/mcp doesn't list extentos (Claude Code)

Restart Claude Code completely — Cmd+Q on macOS, quit from system tray on Windows. Just closing the window isn't enough; the MCP host loads servers at startup.

extentos shows red / errored status (Cursor / Windsurf / Cline)

Click into the server's status to see the error. Most common causes:

• Node.js too old. Run node -v. Extentos requires Node.js 20+. Update from nodejs.org.
• npx command not found. Node.js installed without npx — reinstall a recent Node.js from the official installer.
• Network blocked on first run. npx -y @extentos/mcp-server@latest fetches the package on first run; corporate firewalls or air-gapped environments can block it. Pin a version that's already in the npx cache.
• Config JSON syntax error. Validate with cat ~/.cursor/mcp.json | python -m json.tool (or your tool of choice). A trailing comma or missing bracket prevents the host from parsing the entry.

First tool call hangs for 10–30 seconds

Normal — npx is downloading the package on first run. Subsequent tool calls hit the npx cache and respond in milliseconds.

EACCES or permission errors on first run

Some sandboxed environments restrict npx's cache directory. Set NPX_CACHE to a writable location:

export NPX_CACHE="$HOME/.cache/npx"

Then restart your host.

auth_required returned by createSimulatorSession immediately

You've already consumed the 1000-event anonymous meter on this installId. The response includes a verificationUrl — sign up there with email (free, no payment), and the agent retries automatically. See the auth page for the full flow.

Auto-bind not connecting on Android

Check that nothing else is bound to localhost port 31337. The Extentos library probes the MCP server's local bridge at 127.0.0.1:31337/whoami; if the port is in use, the bridge logs a warning at startup and continues without auto-bind. The developer can still target a session via the URL-bake path (paste the EXTENTOS_SESSION_URL snippet Android-side or write the extentos.session.plist iOS-side that createSimulatorSession returns, then rebuild). To check what's on the port: lsof -i :31337 on macOS / Linux, netstat -ano | findstr 31337 on Windows.

Privacy notice keeps appearing on every tool call

The notice is meant to fire once per install. If it's repeating, the consent file at ~/.extentos/consent isn't being persisted (permissions issue, or EXTENTOS_CONFIG_DIR pointing somewhere unwritable). Run npx @extentos/mcp-server@latest accept-privacy to set consent explicitly.

Uninstalling

To also wipe local state (install ID, auth token, consent):

# macOS / Linux
rm -rf ~/.extentos

# Windows
rmdir /s "%USERPROFILE%\.extentos"

This returns the install to a fresh anonymous tier with a fresh 1000-event meter on next install.

Frequently asked questions

Which MCP host should I use?

Whichever you already use. Extentos is host-agnostic — the same 18 tools work identically across Claude Code, Cursor, Windsurf, and Cline. If you don't have a preference, Claude Code has the cleanest install (one CLI command).

Do I need to install anything else besides the MCP server?

No, not for the MCP-driven dev loop. The MCP server itself includes everything the agent needs to scaffold your project, generate code, and provision simulator sessions. Only when you go to ship to real Ray-Ban Meta hardware do you need a Meta Developer Center account (free, ~15-30 minutes of setup) — see vendors/meta.

Can I use Extentos in a CI environment?

Yes. The MCP server runs over stdio and npx works headlessly. Set EXTENTOS_NO_AUTO_OPEN=1 to disable browser auto-open during simulator sessions. For air-gapped / no-network CI, install the package globally (npm install -g @extentos/mcp-server) so npx doesn't try to fetch.

Does Extentos work in a Docker container?

Yes — install Node.js 20+ in the container, mount ~/.extentos as a volume to persist the installId across runs, and treat the rest like any host. Browser-simulator sessions need network access to wss://api.extentos.com.

Can I install multiple Extentos versions side-by-side?

Each MCP host has one extentos entry at a time, and that entry pins one version. To run multiple versions, register them with different keys: extentos-stable (@0.0.16) and extentos-canary (@latest) as separate entries in the same mcpServers block.

What's the difference between @latest and @0.0.16?

@latest resolves to whatever's newest on npm at fetch time. @0.0.16 pins the exact version. Use @latest for development (you get bug fixes); pin a version when you need reproducibility (e.g., a team is debugging a specific issue and everyone needs the same MCP build).

Will I get a popup or modal during install?

Only the agent-host's standard "approve this MCP server?" dialog the first time you start it after adding the server. Extentos itself doesn't run any GUI. The first browser-simulator session opens a browser tab to extentos.com/s/<sessionId> — you can disable that with EXTENTOS_NO_AUTO_OPEN=1.

Why do I need npx instead of npm install?

npx is the standard pattern for MCP servers — it lets the agent host spawn the server without a global install, ensures version isolation per-host, and makes uninstall as simple as removing the config entry. npm install -g @extentos/mcp-server works too if you prefer a global install (point your command at extentos-mcp directly instead of npx).

Related

• MCP server overview — what the 18 tools do, the canonical agent flow
• Supported agents — per-host capability notes beyond install
• Configuration — environment variables, config files, dial reference
• Auth — the device-code flow that fires after the meter exhausts
• Quickstart with an AI agent — install + first prompt + verify in the simulator end-to-end