# Connect an MCP client to your screens

> Canonical HTML: https://screenrig.ai/docs/mcp/

screenRIG runs a remote MCP server. Point an MCP client at it with an agent
credential and the client gets project tools for screens, playlists, media,
schedules, webhooks and reports.

## The server

| Setting | Value |
| --- | --- |
| URL | `https://api.screenrig.ai/mcp` |
| Transport | Streamable HTTP, stateless. Every request is one `POST`. |
| Protocol | MCP `2026-07-28`, sent as the `MCP-Protocol-Version` header |
| Authentication | `Authorization: Bearer <agent credential>` on every request |
| Responses | JSON, private to the project, never cached |

The server has no sessions and no `initialize` handshake. It refuses `GET`,
`DELETE`, `Mcp-Session-Id`, cookies and older protocol revisions. Each request
authenticates on its own, so a revoked credential stops working on its next
call. Requests are limited to 4 MiB.

The official plugin stays the full workflow: it uploads files, packs
applications and composes pages on your machine. Use the MCP server when your
client calls tools over MCP, and keep the bundled CLI for the
[local work](#use-the-cli-for-these).

## Get a credential

Use the agent credential the bundled CLI already holds after `agent enroll` or
`agent connect`. It is the `token` field of the CLI's private config file,
readable by your user only (`%APPDATA%\screenrig\config.json` on Windows).
Load it into the environment the MCP client runs in, and never paste it into a
conversation:

```sh
export SCREENRIG_MCP_TOKEN="$(jq -r .token ~/.config/screenrig/config.json)"
```

`tools/list` returns only the tools that credential's capabilities allow. The
project's plan entitlements apply on top, exactly as they do for the CLI.

To give the client its own credential, with fewer capabilities and revocable
without disconnecting the CLI, connect a second agent into a separate config
file, approve it in the dashboard, rerun the command until it returns
`data.status: active`, and read the token from that file instead:

```sh
screenrig --config ~/.config/screenrig/mcp.json agent connect \
  --capability screens --capability playlists --print-url
```

## Add the server to your client

Add a remote HTTP server with the URL and an `Authorization` header. In a
client that reads an `mcpServers` file:

```json
{
  "mcpServers": {
    "screenrig": {
      "type": "http",
      "url": "https://api.screenrig.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${SCREENRIG_MCP_TOKEN}"
      }
    }
  }
}
```

The server does not run an OAuth flow. Use a client that sends a custom
`Authorization` header and speaks MCP `2026-07-28`.

Browser pages cannot call the server: a request that carries an `Origin`
header from any other site is refused before authentication.

## Tools

Every tool name starts with `screenrig_`. Tool calls run the same handlers as
the CLI and REST API, with the same project isolation, allowances, credit
charges, rate limits, idempotency and revision checks.

| Area | Tools |
| --- | --- |
| Project and agent | `project_get`, `project_update` (rename), `agent_status`, `project_credential_revoke` |
| Invitations | `invitation_create` (email only), `invitation_list`, `invitation_revoke` |
| Screens | `screen_list`, `screen_get`, `screen_pair`, `screen_update`, `screen_archive`, `screen_unarchive`, `screen_rotate_public_id`, `screen_toast`, `screen_screenshot`, `screen_screenshot_current`, `screen_reboot` |
| Fleet actions | `screen_actions`: one action across screens chosen by ID or tag |
| Schedules and takeover | `screen_playlist_schedule_get`, `_set`, `_clear`; `screen_takeover_set`, `_clear` |
| Display power | `screen_display`, `screen_display_clear`, `screen_display_schedule_get`, `_set`, `_clear` |
| Playlists | `playlist_list`, `playlist_get`, `playlist_create`, `playlist_update`, `playlist_delete` |
| Media | `media_list`, `media_get`, `media_update`, `media_delete`, `media_generate` |
| Applications | `application_list`, `application_get`, `application_update` (rename) |
| Application K/V | `kv_list`, `kv_get`, `kv_set`, `kv_delete` |
| Comments | `comment_get`, `comment_set`, `comment_delete` |
| Webhooks | `webhook_list`, `webhook_get`, `webhook_create`, `webhook_update`, `webhook_delete`, `webhook_test`, `webhook_deliveries` |
| Operations | `operation_get`, `operation_wait`, `operation_cancel` |
| Events and playback | `event_list`, `playback_list`, `playback_plays_list` |
| Feedback | `feedback_bug_submit`, `feedback_bug_list`, `feedback_feature_submit`, `feedback_feature_list` |
| Service | `capabilities_get`, `server_status`, `browser_link_claim` |

### How the tools behave

- **Paging.** List tools return one page, newest first (K/V in key order).
  Pass a non-null `next_cursor` back as `after`, with the same filters, for the
  next page.
- **Retries.** Writes accept an optional `idempotency_key`. Reuse it to retry
  the same write safely; omit it to start a fresh request. Pairing, toasts,
  screenshots, image generation, invitations, browser links, operation cancels
  and feedback require one, and their input schemas say so.
- **Revisions.** Writes accept an optional `revision`. A stale revision is
  refused: read the resource again, reapply the change and retry.
- **Screenshots.** `screen_screenshot` waits up to 60 seconds and returns the
  capture as `image/webp` image content. `screen_screenshot_current` returns the
  last ready still and its `captured_at` time without asking for a new capture.
- **Secrets stay out.** Webhook results never carry the signing secret and
  reduce each receiver URL to its origin. Invitations go by email only, so no
  invitation link reaches the model.
- **Revoking.** `project_credential_revoke` disconnects the agent whose
  credential made the call, so with the CLI's credential it disconnects the CLI
  too. It requires `confirmation: "REVOKE"`, and
  `allow_last_agent: true` to disconnect the project's last active agent. The
  project and its content remain.
- **Errors.** A refused call returns a tool error whose structured content is
  the REST API's problem document, with `code`, `detail` and `status`. The result's `screenrig/result` metadata carries `http_status`, and
  `etag`, `credit_remaining` or `retry_after` when the server sent them.

## Resources

Resources expose metadata only. They are private to the project and never
cached.

| URI | Contents |
| --- | --- |
| `screenrig://project` | The authenticated project |
| `screenrig://screens/{id}` | One screen |
| `screenrig://playlists/{id}` | One playlist |
| `screenrig://media/{id}` | One media item's metadata |
| `screenrig://applications/{id}` | One application |
| `screenrig://operations/{id}` | One asynchronous operation |

## Use the CLI for these

These steps move files or secrets, or run on your machine, so they stay in the
[bundled CLI](https://screenrig.ai/docs/cli.md):

| Task | CLI |
| --- | --- |
| Create a project | `screenrig agent enroll --email ADDRESS` |
| Connect another agent | `screenrig agent connect` |
| Upload media files | `screenrig media upload` |
| Pack and upload an application | `screenrig app pack`, `screenrig app upload` |
| Compose pages and use templates | [Compose](https://screenrig.ai/docs/compose.md) |
| Get or rotate a webhook signing secret | `screenrig webhooks create` prints it once; `screenrig webhooks rotate-secret` |
| Send an invitation link | `screenrig invitations create --link` |
| Follow events live | `screenrig events follow` (over MCP, poll `screenrig_event_list`) |
| Export plays as CSV | `screenrig playback plays --format csv` |

## Related

- [Start](https://screenrig.ai/docs/start.md): install the official plugin and its bundled CLI.
- [CLI reference](https://screenrig.ai/docs/cli.md): every command, with the same conventions as the tools above.
- [API reference](https://screenrig.ai/docs/api.md): the REST contract and problem types the tools share.