> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glasswarp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect via MCP

> Give Claude, Cursor, or any MCP client eyes and hands on a Windows PC you or your client already own — no integration code.

Glasswarp ships a **remote MCP server** so MCP-enabled assistants and IDEs get
eyes and hands on a paired Windows PC without writing project code. Built for
automation developers driving no-API Windows apps (and for agent builders).
You bring the brain (the model and the prompts); Glasswarp provides vision, native input,
and a safe session.

Marketing overview: [glasswarp.com/mcp](https://www.glasswarp.com/mcp).
Open-source server: [github.com/glasswarp/mcp-server](https://github.com/glasswarp/mcp-server).

<Note>
  MCP sessions are ordinary metered Platform API sessions — same concurrency,
  active minutes, consent, indicator, kill switch, and audit as REST / SDK.
</Note>

## Prerequisites

<Steps>
  <Step title="Install and pair a Windows PC">
    The PC owner [installs the host](/get-started/install-host) with no
    Glasswarp account. You [pair the tray code](/get-started/pair-rig) while
    logged in and turn on **API access**.
  </Step>

  <Step title="Create an API key">
    [Console → API Keys](https://www.glasswarp.com/console/keys). Same `gw_*`
    key authenticates REST and MCP. Copy it once when created.
  </Step>

  <Step title="Host online">
    `rigs.list` only marks a rig **USABLE** when it is online **and**
    API-enabled. Start the Windows host agent before asking the assistant to act.
  </Step>
</Steps>

## Endpoint

| | |
| - | - |
| URL | `https://mcp.glasswarp.com/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer <glasswarp_api_key>` |
| Platform API | `https://signal.glasswarp.com` (same sessions / metering) |

## Client config

Use your **real** API key from the console — not placeholder text.

### Cursor (recommended)

<a href="https://cursor.com/en/install-mcp?name=glasswarp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBnbGFzc3dhcnAvbWNwIl0sImVudiI6eyJHTEFTU1dBUlBfQVBJX0tFWSI6IllPVVJfQVBJX0tFWSJ9fQ%3D%3D">
  <img alt="Add to Cursor" height="32" src="https://cursor.com/deeplink/mcp-install-dark.svg" />
</a>

One-click install uses `npx -y @glasswarp/mcp`. Set `GLASSWARP_API_KEY` to your
console key when prompted.

Current Cursor builds often fail remote Streamable HTTP with `fetch failed`.
Bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) over stdio,
and use an **absolute** `npx` path for your OS (bare `npx` often breaks inside
Cursor.app).

<AccordionGroup>
  <Accordion title="macOS (Apple Silicon)">
    ```json theme={null}
    {
      "mcpServers": {
        "glasswarp": {
          "command": "/opt/homebrew/bin/npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.glasswarp.com/mcp",
            "--header",
            "Authorization:${GLASSWARP_AUTH}"
          ],
          "env": {
            "PATH": "/opt/homebrew/bin:/usr/bin:/bin",
            "GLASSWARP_AUTH": "Bearer gw_live_sk_REPLACE_WITH_YOUR_KEY"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="macOS (Intel)">
    ```json theme={null}
    {
      "mcpServers": {
        "glasswarp": {
          "command": "/usr/local/bin/npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.glasswarp.com/mcp",
            "--header",
            "Authorization:${GLASSWARP_AUTH}"
          ],
          "env": {
            "PATH": "/usr/local/bin:/usr/bin:/bin",
            "GLASSWARP_AUTH": "Bearer gw_live_sk_REPLACE_WITH_YOUR_KEY"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Windows">
    ```json theme={null}
    {
      "mcpServers": {
        "glasswarp": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.glasswarp.com/mcp",
            "--header",
            "Authorization:${GLASSWARP_AUTH}"
          ],
          "env": {
            "GLASSWARP_AUTH": "Bearer gw_live_sk_REPLACE_WITH_YOUR_KEY"
          }
        }
      }
    }
    ```

    If Cursor cannot find `npx`, use the full path from Node.js (often
    `C:\\Program Files\\nodejs\\npx.cmd`).
  </Accordion>

  <Accordion title="Linux">
    ```json theme={null}
    {
      "mcpServers": {
        "glasswarp": {
          "command": "/usr/bin/npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.glasswarp.com/mcp",
            "--header",
            "Authorization:${GLASSWARP_AUTH}"
          ],
          "env": {
            "PATH": "/usr/bin:/bin",
            "GLASSWARP_AUTH": "Bearer gw_live_sk_REPLACE_WITH_YOUR_KEY"
          }
        }
      }
    }
    ```

    If `npx` lives elsewhere (nvm, fnm), point `command` at that absolute path.
  </Accordion>
</AccordionGroup>

Toggle the server off/on after saving.

### Direct remote URL

```json theme={null}
{
  "mcpServers": {
    "glasswarp": {
      "url": "https://mcp.glasswarp.com/mcp",
      "headers": {
        "Authorization": "Bearer gw_live_sk_REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}
```

After reload, the client should list tools such as `rigs.list`, `session.start`,
`screen.observe`, `input.click_target`, `input.type_text`, `input.send_actions`, `app.launch`, `demos.list`, `demos.get`,
`session.live_view`, and `session.end`.

## First session

Ask your assistant:

> Open Notepad on my PC and type hello from MCP.

Typical tool flow:

`rigs.list` → `session.start` → `screen.observe` (text+targets; `image=true` if you need vision) → `input.send_actions` (or click/type) → verify from the batch result → `session.end`

An invalid action is caught during validation **before any event is sent** and
the response reports its index (nothing executed). The owner kill switch and
session end abort an **in-flight** batch on agent **≥ 0.2.21** (`api_input_ack`):
the call returns **`410 aborted_by_owner`** with `executed` / `aborted` /
`kill_to_abort_ms` — only `executed` events landed. Older hosts are
fire-and-forget; upgrade for guaranteed mid-batch abort.

Always end the session when finished. Idle sessions auto-end after about
**15 minutes**.

## What to expect from your assistant

On connect, the server gives every MCP client behavioral guidance. In practice:
your assistant handles quick tasks directly in chat — look at the screen, click,
type, and batch predictable sequences. For longer multi-step work in a
code-capable client, it will offer to write a small SDK agent that runs the loop
at full speed instead of one chat turn per step — your choice either way.
Chat-only clients simply keep working through MCP tools.

Details and the pre-built demo catalog:
[Ways to run agents](/guides/ways-to-run-agents).

## Live View (human in the loop)

`session.live_view` returns a **console** deep link. The **rig owner** must be
signed into Glasswarp to watch at \~60fps and intervene. API keys alone cannot
open the console player — that preserves owner consent. See
[Live View](/guides/live-view).

## Tools (v1)

| Tool | Role |
| - | - |
| `rigs.list` | List paired rigs |
| `session.start` / `session.end` | Session lifecycle |
| `screen.observe` | Text + UIA targets by default; set `image=true` for a verification-grade JPEG (`max_width` 960 / quality \~60). JPEG omitted when `changed=false` |
| `input.click_target` / `input.click_xy` | Mouse (prefer targets; `input.click_xy` uses **native** capture coords) |
| `input.type_text` / `input.send_keys` / `input.drag` / `input.scroll` | Keyboard and pointer (prefer bundling into `input.send_actions`) |
| `input.send_actions` | Up to 10 predictable actions in one call; `observe_after` defaults true with **text** verify (`observe_image=true` for JPEG) |
| `app.launch` | Start an app on the host (`args` optional) |
| `demos.list` / `demos.get` | Pre-built demo catalog (install + command; they do not run the demos) |
| `session.live_view` | Owner console Live View URL |
| `session.status` | Session status |

**Prompts:** `best_practices`, `demo_mona_lisa`, `demo_minesweeper`

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cursor: ENOENT / bare npx fails">
    Bare `npx` is often broken in Cursor’s spawn environment. Use the absolute
    `npx` path for your platform from the Cursor section above (Apple Silicon
    Homebrew, Intel Homebrew, Windows Node.js, or Linux).
  </Accordion>

  <Accordion title="fetch failed / ByteString / ellipsis in header">
    Do not paste truncated keys with `…`. Use the full `gw_live_sk_…` value from
    the console. Prefer the stdio `mcp-remote` bridge on Cursor.
  </Accordion>

  <Accordion title="rigs.list works but rig is not usable">
    Online=false means the Windows host agent is not connected. Start
    GlasswarpHost on that PC; keep **API access** enabled in Console → Rigs.
  </Accordion>

  <Accordion title="Platform API hostname does not resolve">
    If `signal.glasswarp.com` (or your configured API base URL) fails to resolve
    on your machine, flush your local DNS cache or try a public resolver
    (for example `1.1.1.1` or `8.8.8.8`). The MCP server reaches the Platform
    API from its own network — local DNS only affects tools you run on your
    machine.
  </Accordion>
</AccordionGroup>

## Building a product instead?

Use the [Python SDK](/quickstart) and [Setup for Agents](/setup-for-agents).
MCP is for assistants out of the box; the SDK is for products you ship.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.