Configuration
Configure @extentos/mcp-server — environment variables, the ~/.extentos state files (install id, auth, consent), and the default vendor.
The MCP server needs no configuration to run — npx -y @extentos/mcp-server@latest works out of the box, anonymously, with sensible defaults. The settings below are escape hatches: override the backend for local Extentos development, relocate the state directory, opt out of telemetry, suppress browser auto-open, or feed the setup diagnostic your GitHub Packages token.
This page is about the MCP-server shell, not the library. The Kotlin/Swift SDK has its own separate config surface —
ExtentosConfig(debug,telemetryConsent, …) is set in the host app's bootstrap, not via these environment variables. See the SDK docs for that surface.
Environment variables
All settings are environment variables; there is no config file you author by hand. Every variable is optional.
| Variable | Default | What it does |
|---|---|---|
EXTENTOS_BACKEND_URL | Production backend (api.extentos.com) | Override the backend base URL the server talks to. Used when developing Extentos itself against a local backend. Read by tools/util/backendClient.ts. |
EXTENTOS_CONFIG_DIR | ~/.extentos | Relocate the state directory (install id, auth token, consent). Useful for sandboxes, CI, or devcontainers that can't write to the home directory. |
EXTENTOS_TELEMETRY | unset | Set to 0 to decline anonymous telemetry for the shell without running the CLI consent command. Takes precedence over the on-disk consent file (the escape hatch for environments that can't persist consent). |
EXTENTOS_NO_AUTO_OPEN | unset | Set to 1 to suppress the browser auto-open on simulator-session creation (headless / SSH / sandboxed environments). The session URL is still returned in the tool response for the developer to open manually — nothing is lost. |
GITHUB_TOKEN | unset | Read by extentos-mcp setup to validate the Meta DAT GitHub-Packages PAT, needed only for camera/display apps that depend on com.extentos:glasses-meta (those mwdat-* artifacts live on GitHub Packages and need a token with read:packages scope). This is a setup-diagnostic input, not a runtime dial — the running MCP server never reads it; only the setup subcommand does. |
GITHUB_USERNAME | token | Optional companion to GITHUB_TOKEN for the same setup diagnostic — the Basic-auth username for the GitHub Packages Maven endpoint. Defaults to the literal token (GitHub accepts any username when the password is a valid PAT). |
EXTENTOS_TELEMETRY and EXTENTOS_CONFIG_DIR are the only ones that change persistent state; the rest are per-process.
State files
The server keeps a small amount of state under ~/.extentos (override the directory with EXTENTOS_CONFIG_DIR):
| File | Holds |
|---|---|
install.json | The stable anonymous installId (inst_…) tagged onto every backend request and telemetry event, plus first-run metadata. Not a secret — it's the same value sent to api.extentos.com on every tool call. |
auth.json | The bearer token written after account linking. Present only once linked; cleared by extentos-mcp logout. |
consent | One of accepted / declined — the telemetry consent decision. Absent until you run accept-privacy / decline-privacy. EXTENTOS_TELEMETRY=0 overrides it. |
The auth and consent lifecycle is documented in full on the auth page. You never edit these files by hand — the CLI subcommands (login, logout, accept-privacy, decline-privacy, whoami, status) manage them.
Default vendor
The only glasses vendor in the current MVP is meta_rayban — every tool that takes a glasses argument requires it. There is no vendor-selection setting; the value is passed per tool call (e.g. getPlatformInfo({ glasses: "meta_rayban" }), generateConnectionModule({ glasses: "meta_rayban", … })). Additional vendors will surface as new accepted values on those tools when they ship.
Related
- Auth — the device-code flow,
auth.json, and the CLI auth commands that manage the state files above - MCP server overview — the tool catalog, the canonical agent flow, and the CLI subcommands
- Setup and Generation tools —
generateConnectionModule, which references theGITHUB_TOKENsetup diagnostic for the Meta DAT repo - Install — per-host install commands and JSON snippets
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.
Credentials checklist
Provider-keys checklist for Extentos. Simulator needs none; Phase-4 assistant defaults to the managed gateway; handler calls are BYOK; Meta creds for hardware only.