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

# MCP server

> Let AI agents drive slipway over the Model Context Protocol — bring up environments, read logs, run commands, and check usage.

slipway ships a first-party [Model Context Protocol](https://modelcontextprotocol.io) server, so AI coding agents (Claude Code, Claude Desktop, Cursor, …) can drive your environments directly. An agent can bring up an isolated environment from a branch, get a live URL, read logs, run commands to verify its work, check how much capacity you have left, then tear it down — the verification loop agents otherwise lack.

The server is read-and-write and **role-gated**: every token carries a role, and each tool requires a minimum role.

## Create a token

In the console, go to **Settings → MCP** (admin only) and choose **New token**. Give it a name, pick a role, and optionally an expiry. The token is shown **once**, right after you create it — copy it then. If you lose it, revoke it and make a new one.

Tokens are scoped to a single organization and can be revoked at any time from the same page.

## Connect your agent

The endpoint is `https://<your-slipway-host>/mcp`. For **Claude Code**:

```bash theme={"system"}
claude mcp add --transport http slipway https://<your-slipway-host>/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"
```

For **Cursor** or **Claude Desktop**, add an HTTP MCP server with the same URL and an `Authorization: Bearer YOUR_TOKEN` header.

## Roles

A token's role caps what its agent can do. Each tool requires at least the role shown.

| Role          | Can do                                                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **viewer**    | Read environments, deployments, logs, events, repos, specs, and usage.                                                 |
| **developer** | Everything a viewer can, plus bring up instances, deploy/redeploy, cancel, tear down, and run commands in a container. |
| **admin**     | Everything, plus writing variables and secrets.                                                                        |

Give an agent the **lowest role that lets it do its job** — a read-only agent that just inspects builds only needs `viewer`.

## What an agent can do

The tools group into four areas:

* **Capacity** — `get_usage` (plan + environments / concurrent deployments / seats / storage, each used vs. cap) and `check_capacity` (can I start another environment right now?). Agents should check these before bringing things up so they don't hit your concurrency cap.
* **Read** — list and inspect environments, deployments, logs, and repositories; read a repo's resolved spec.
* **Lifecycle** — bring up a fresh instance from a branch, wait for it to go healthy, redeploy, cancel, and tear down.
* **Exec** — run a command in a running service and capture its output (for example, run your tests).
* **Config** — set variables and secrets.

## Security

* Tokens are stored hashed; the plaintext only exists at create time.
* Every tool is scoped to the token's organization — an agent can never reach another org's data.
* The `exec` and secret-writing tools are powerful (arbitrary commands in your pods; secret values). Keep tokens to the minimum role, prefer short expiries for shared machines, and revoke anything you're unsure about.