---
title: Install the MCP server
description: 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.
type: tutorial
platform: mcp
related:
  - /docs/mcp-server
  - /docs/mcp-server/agents
  - /docs/mcp-server/configuration
  - /docs/mcp-server/auth
  - /docs/getting-started/with-agent
---

The Extentos MCP server (`@extentos/mcp-server`, MIT) is published on npm and installs into any [Model Context Protocol](https://modelcontextprotocol.io)-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](#generic-mcp-host) section.
- **No Extentos account needed for install.** Discovery, validation, and guidance tools work anonymously; the [auth flow](/docs/mcp-server/auth) fires the first time you call `createSimulatorSession` — or `generateConnectionModule`'s scaffold step, which mints your account-bound project key (same free device-code login).

**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:

```text
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:

```bash
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 of Extentos's 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:

```json
{
  "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 Extentos's 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:

```json
{
  "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:

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

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

| Platform | Path |
|---|---|
| macOS | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
| Windows | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` |
| Linux | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |

**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:

```json
{
  "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:

```json
{
  "mcpServers": {
    "extentos": {
      "command": "npx",
      "args": ["-y", "@extentos/mcp-server@<version>"]
    }
  }
}
```

Why pin: Extentos is pre-1.0 (find the current version on [npm](https://www.npmjs.com/package/@extentos/mcp-server)). 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:

```bash
claude mcp add extentos -- npx -y @extentos/mcp-server@<version>
```

## 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:

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

# Windows
rmdir /s "%LocalAppData%\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:

```text
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](#troubleshooting) below.

Per-host verification methods:

| Host | Verify command |
|---|---|
| Claude Code | `/mcp` — lists active MCP servers |
| Cursor | MCP settings panel shows `extentos` with green status |
| Windsurf | MCP / tools panel shows `extentos` |
| Cline | MCP Servers tab shows `extentos` with green status |
| Any | Ask the agent: *"Run getPlatformInfo for meta_rayban"* |

The full tool list is the generated [MCP tools reference](/docs/reference/mcp-tools); see [`/docs/mcp-server`](/docs/mcp-server) for the catalog overview.

## 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](https://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 npm's cache directory (which `npx` uses). Point it at a writable location:

```bash
npm config set cache "$HOME/.cache/npm"
# or, per-session:
export npm_config_cache="$HOME/.cache/npm"
```

Then restart your host.

### `auth_required` returned by `createSimulatorSession` immediately

That's the expected flow on first use — the browser simulator requires a free Extentos account. The response includes a `verificationUrl`; open it in your browser, sign in (Google one-click or email + password — no payment), and the agent retries automatically. See the [auth page](/docs/mcp-server/auth) 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

| Host | Command |
|---|---|
| Claude Code | `claude mcp remove extentos` |
| Cursor / Windsurf / Cline / generic | Delete the `"extentos"` entry from the host's `mcp.json` (or equivalent), then restart |

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

```bash
# macOS / Linux
rm -rf ~/.extentos

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

This returns the install to a fresh anonymous state on next install — the next `createSimulatorSession` call will trigger the device-code flow again.

## Frequently asked questions

### Which MCP host should I use?

Whichever you already use. Extentos is host-agnostic — the same 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](/docs/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` (pinned to an exact version) and `extentos-canary` (`@latest`) as separate entries in the same `mcpServers` block.

### What's the difference between `@latest` and a pinned version?

`@latest` resolves to whatever's newest on npm at fetch time. Pinning an exact version (`@extentos/mcp-server@<version>`, with the current version from the [npm page](https://www.npmjs.com/package/@extentos/mcp-server)) locks it. 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](/docs/mcp-server)** — what the tools do, the canonical agent flow
- **[Supported agents](/docs/mcp-server/agents)** — per-host capability notes beyond install
- **[Configuration](/docs/mcp-server/configuration)** — environment variables, config files, dial reference
- **[Auth](/docs/mcp-server/auth)** — the device-code flow that fires on the first browser-simulator session
- **[Quickstart with an AI agent](/docs/getting-started/with-agent)** — install + first prompt + verify in the simulator end-to-end