# teleport-mcp

An [MCP](https://modelcontextprotocol.io) server that lets an LLM agent drive a TeleportXR
headless client: connect to Teleport servers, move an avatar, send input, and inspect the
geometry a server has streamed.

## Why this exists

The headless client is two processes. `teleportd` is a service that owns live streaming
connections; `teleport_cli` is a thin front end that sends it commands and exits. That split
is what makes agent control possible at all: an agent issues a command, reports to the user,
waits for feedback, and acts again — three tool calls that may be minutes apart. A session
that died with its terminal could not support that flow.

This package is the adapter. It speaks MCP over stdio to the agent, and the
[local control protocol](../Teleport/docs/protocol/local_control.rst) over a loopback socket
to `teleportd`.

## Requirements

- Node 22 or later.
- A `teleportd` binary. Build it from the `Teleport/` repo:
  ```bash
  cd ../Teleport && cmake -B build_pc_client -S . && cmake --build build_pc_client
  ```

## Install

```bash
npm install
```

## Configure

### Claude Code

Add to `.mcp.json` at the root of the workspace:

```json
{
  "mcpServers": {
    "teleport": {
      "command": "node",
      "args": ["teleport-mcp/src/index.js"]
    }
  }
}
```

### Claude Desktop

Absolute paths, since the working directory is not the workspace:

```json
{
  "mcpServers": {
    "teleport": {
      "command": "node",
      "args": ["/home/you/teleport/teleport-mcp/src/index.js"],
      "env": {
        "TELEPORTD_PATH": "/home/you/teleport/Teleport/build_pc_client/bin/teleportd"
      }
    }
  }
}
```

### Environment

| Variable | Purpose |
|---|---|
| `TELEPORT_SERVICE_PORT` | Control port. Default 10510. |
| `TELEPORTD_PATH` | Path to the `teleportd` binary. Searched first, before the build trees and `PATH`. |
| `TELEPORT_MCP_NO_AUTOSTART` | Set to `1` to require a service that is already running (systemd, launchd, a terminal). |

## Tools

| Tool | Does |
|---|---|
| `teleport_overview` | Service version, all connections, current identity — start here |
| `teleport_connect` | Open a connection; returns its id |
| `teleport_list_connections` | Every open connection with its state |
| `teleport_connection_status` | State, server, latency, inputs and mode for one connection |
| `teleport_disconnect` | Close one connection |
| `teleport_set_pose` | Move and/or turn the avatar |
| `teleport_list_inputs` | Inputs the server has declared |
| `teleport_send_input` | Send a binary, analogue or motion input event |
| `teleport_set_mode` | `minimal` (network diagnostic) or `simulated` (full geometry flow) |
| `teleport_get_geometry` | Summary, node list, or pointer resources |
| `teleport_identity` | Show, start or clear the sign-in |
| `teleport_raw_command` | Any control command verbatim — the escape hatch |

Every tool returns the service's JSON `data` object as `structuredContent`, alongside a text
rendering of the same object.

## The agent flow

```
teleport_overview                      → is anything already connected?
teleport_connect  address=host:8080    → { id: 1 }
teleport_connection_status  id=1       → poll until state is CONNECTED
teleport_set_mode  id=1 mode=simulated
teleport_get_geometry  id=1 what=nodes → what the server sent
```

Two things that are not guessable, and that the tool descriptions repeat:

- **`teleport_connect` returns before the connection completes.** The id is valid immediately;
  the connection is still negotiating. Poll `teleport_connection_status` until `state` is
  `CONNECTED`.
- **Connections outlive the conversation.** A connection opened in one session is still there
  in the next. Call `teleport_overview` before assuming you need a new one.

### Signing in

Sign-in is an OAuth device-code flow, and the service has no browser. `teleport_identity` with
`action: "signin"` starts it; poll `action: "show"` and read `pendingSignIn` for the URL and
code to relay to the user.

### Shutting down

`shutdown` stops the service and every live stream with it. It is deliberately not a tool —
reach it through `teleport_raw_command` if you mean it.

## Development

```bash
npm test        # framing, dot-stuffing, reconnect, and the command mapping
node smoke.mjs  # end-to-end: spawns the server, autostarts teleportd, calls every tool
```

`smoke.mjs` honours `TELEPORT_SERVICE_PORT`, so run it on a scratch port (`10599`) rather than
against a service you are using.

## How it talks to the service

The control protocol is one request line in, dot-stuffed lines out, terminated by a lone `.`,
with an `OK` / `ERROR <message>` status header. Three properties shape `src/control-client.js`:

- **No message ids.** A socket carries one request at a time, so concurrent tool calls queue
  rather than interleave.
- **Session state is per-socket.** The output format and the selected connection are lost if
  the socket drops, so the client re-sends `format json` on every connect and re-selects the
  connection before every connection-scoped command rather than trusting an earlier `use`.
- **uids are strings.** `avs::uid` is 64-bit and Teleport's uids exceed 2^53, so they cross the
  wire as decimal strings — the same convention `teleport-web-client` and `teleport-nodejs` use.

`src/daemon.js` starts the service if it is not running and **never stops it**. That is the
point of the split.

## Licence

MIT.