Connect an MCP client to your screens

The server

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.

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:

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:

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:

{
  "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.

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.

Use the CLI for these

These steps move files or secrets, or run on your machine, so they stay in the bundled CLI:

Related

• Start: install the official plugin and its bundled CLI.
• CLI reference: every command, with the same conventions as the tools above.
• API reference: the REST contract and problem types the tools share.