MCP server

The MCP server is how an AI agent — Claude Code, Cursor, Windsurf, Cline, or any Model Context Protocol-compatible host — operates Extentos. The agent invokes deterministic tools; the server reads project state, generates code, mutates the AppSpec, brokers simulator sessions, and queries debugging traces. The server itself has no planning tool — agents are better planners than regex bundles. Tools are typed primitives the agent composes in sequence.

This page is the section landing — what the server is, the 18 tools at a glance, the canonical agent-driven flow, configuration knobs, the CLI, and how the auth model works. Sub-pages cover each in depth.

Install

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

For non-Claude-Code hosts, see the agent prompt or manual JSON install paths. Full install reference at /docs/mcp-server/install.

The 18 tools, by category

The server exposes exactly 18 tools (verified in mcp-server/src/tools/definitions.ts), organized into 7 categories. The categories are the agent's mental map; an agent that understands which category a tool lives in can decide when to call it.

1. Discovery and Planning (2 tools)

The first calls in any new task. Cheap, all local, no side effects.

2. Setup and Generation (4 tools)

The mutation tools that scaffold the project and the AppSpec. Run in this order on a fresh project.

3. Implementation Guidance (2 tools)

Side-quest tools the agent calls during composition.

4. Validation (3 tools)

Correctness gates. Run after every mutation.

5. Simulation (4 tools)

Provision and operate browser-based simulator sessions.

6. Production (2 tools)

Pre-ship checks.

7. Documentation (1 tool)

Full per-tool reference with input schemas, response shapes, and worked examples: /docs/mcp-server/tools.

The canonical agent-driven flow

In a fresh project, the agent invokes the tools in this order:

1. getPlatformInfo({ sections: ["version", "capabilities"], glasses: "meta_rayban" })
2. searchDocs({ topic: "trigger_types" | "action_types" | "block_types" })
3. generateConnectionModule({ platform, glasses, appPackage })
   → returns "needs_placement" question
4. generateConnectionModule({ ... placement: "<chosen>" })
   → writes scaffold files
5. initSpec({ ... })
   → first AppSpec written
6. generateConsumer({ kind: "callback" })
   → handler stubs written
7. validateIntegration()
   → ✓ all good (or returns structured errors to fix)
8. createSimulatorSession({ glasses, spec })
   → returns sessionId; auto-opens browser at extentos.com/s/<id>
   → if running app is reachable via local bridge, it auto-attaches
9. <developer interacts with the simulator; events flow into the backend>
10. getEventLog({ sessionId, filter: "errors" })  → debug
    getSimulatorStatus({ sessionId })             → status

For iteration, the loop is inspectIntegration (for the freshness token) → updateSpec → generateConsumer (if handlers/streams added) → validateIntegration. Before shipping, getProductionChecklist and getCredentialGuide.

Configuration

The MCP server reads these environment variables (verified in mcp-server/src/):

Full configuration reference: /docs/mcp-server/configuration.

CLI subcommands

Running npx @extentos/mcp-server@latest with no arguments starts the MCP server over stdio (the path the agent uses). With a subcommand, it acts as a developer CLI:

Full CLI reference: /docs/mcp-server/auth.

Auth model

The MCP server is anonymous-first. All 18 tools work with no account. The first browser-simulator session is anonymous, keyed to a per-machine installId at ~/.extentos/install_id.

The 1000-event meter is the only gate. When it exhausts, createSimulatorSession returns status: "auth_required" with a verification URL. The agent calls completeAuthLink to poll the backend; the developer signs up with email (no payment) at the URL; the backend issues a token; the original tool call retries automatically.

There is no paid tier at launch. Full auth model: /docs/mcp-server/auth and /docs/resources/pricing.

Privacy and telemetry

On first run, the MCP server injects a one-time privacy notice into the response. Telemetry is anonymous (tagged with installId, no source code or personal data) and is dismissed-by-continuing by default — same pattern as Vercel CLI, Astro, Vite. Decline at any time:

npx @extentos/mcp-server@latest decline-privacy
# or
EXTENTOS_TELEMETRY=0 (env var, persistent for the shell)

Privacy notice content is in mcp-server/src/index.ts (PRIVACY_NOTICE constant). Notice is shown once per install via claimFirstPrivacyNotice — never repeats.

Compatible MCP hosts

Verified to work with:

• Claude Code — primary target. One-line install via claude mcp add.
• Cursor — JSON config in ~/.cursor/mcp.json.
• Windsurf — JSON config in ~/.codeium/windsurf/mcp_config.json.
• Cline — JSON config in Cline's MCP settings.
• Any MCP-compatible host — drop the standard mcpServers.extentos JSON block in.

The MCP server speaks the standard MCP protocol over stdio (@modelcontextprotocol/sdk); no host-specific code paths exist on the server side. Per-host install steps: /docs/mcp-server/agents.

The local bridge — auto-bind dev loop

When the server starts, it opens a 127.0.0.1:31337/whoami HTTP listener (mcp-server/src/localBridge.ts). The Extentos library on the developer's app probes this endpoint at runtime to learn its host MCP's installId. The result: every createSimulatorSession call from the agent auto-attaches the running app to the new session — no rebuild, no URL paste.

Reach paths:

• Android emulator: http://10.0.2.2:31337/whoami (host-loopback NAT alias)
• iOS Simulator: http://localhost:31337/whoami (shares host network namespace)
• Physical Android phone via USB: adb reverse tcp:31337 tcp:31337 once, then localhost:31337 from the device
• Cellular phone or cloud-hosted agent: probe times out. The agent uses the URL-bake path instead — createSimulatorSession returns a BuildConfig.EXTENTOS_SESSION_URL snippet (Android) or extentos.session.plist payload (iOS) the developer pastes in, then rebuilds the app once. Less elegant than auto-bind but works on any topology.

Bound to 127.0.0.1 only. The installId is not a secret — it's the same value the MCP sends to api.extentos.com on every tool call. No auth needed at this layer.

If port 31337 is in use (rare; another MCP instance already running), startup logs a warning and continues. Auto-bind silently fails for that session; the developer uses the URL-bake path (paste the EXTENTOS_SESSION_URL Android snippet or write the extentos.session.plist iOS payload that createSimulatorSession returns, then rebuild). The agent and tools keep working — only the zero-rebuild auto-attach is lost until the port frees up.

Status

• Package: @extentos/mcp-server@0.0.16 on npm (MIT license)
• Engines: Node.js 20+
• Source: github.com/Asgermolgaard/vibe-hardware/tree/master/mcp-server
• Pre-1.0 — APIs may shift between minor versions until the hardware test loop closes. Pin to an exact version (@0.0.16) if you need cross-session reproducibility.

Related

• Quickstart with an AI agent — install the server and walk through a real dev loop
• Tools reference — full per-tool API
• Configuration — environment variables, config files, install-time settings
• Auth — device-code flow, account linking, CLI auth commands
• Supported agents — per-host install instructions
• Architecture — how the MCP server fits into the broader Extentos system
• Transport vs app simulation — what the simulator the MCP brokers actually does