Connect AI agents to Shots

Authentication

Every call acts for one workspace. Agents that take a header send a workspace API key as Authorization: Bearer ss_…; create one in Settings → AI agents with only the scopes the agent needs. Claude.ai, Claude Desktop, and ChatGPT connect through OAuth instead: you sign in to Shots, choose the scopes, and approve. The token they receive is a workspace API key with exactly those scopes, listed and revocable in Settings.

Calls pass the same checks as the API: the key's scope, an active plan, the operation's feature, and its quota. Each key may make 60 calls a minute. Refusals use the API error envelope.

Tools

Each tool is named after the API operation it mirrors and takes the same input. An agent sees only the tools its key's scopes allow.

Claude Code

Terminal

claude mcp add --transport http shots https://shots-mcp.playbookmedia.io/mcp \
  --header "Authorization: Bearer $SHOTS_API_KEY"

1. Run the command, then /mcp in Claude Code to check that shots is connected.
2. Without the --header line, Claude Code connects through OAuth: run /mcp, pick shots, and approve it in your browser.
3. Or install the Shots plugin, which adds the server (over OAuth) and a launch skill: /plugin install shots --marketplace PlaybookMediaLLC/screenshot-studio.

Claude.ai and Claude Desktop

Claude.ai or Claude Desktop → Settings → Connectors → Add custom connector

https://shots-mcp.playbookmedia.io/mcp-oauth-claude

1. Name the connector Shots and paste the URL.
2. Select Connect and sign in to Shots. Pick the scopes the connector may use, then approve.
3. Claude Desktop uses the same connectors as Claude.ai once you are signed in.

ChatGPT

ChatGPT → Settings → Apps & Connectors → Advanced → Developer mode → Create

https://shots-mcp.playbookmedia.io/mcp-oauth-dynamic

1. Name the connector Shots, paste the URL, and choose OAuth.
2. Sign in to Shots when ChatGPT opens it, pick the scopes, and approve.
3. The listed Shots app in the ChatGPT directory connects through /mcp-oauth-chatgpt with its registered client; a developer-mode connector registers itself through the URL above.

Cursor

~/.cursor/mcp.json, or .cursor/mcp.json in a project

{
  "mcpServers": {
    "shots": {
      "headers": {
        "Authorization": "Bearer ${env:SHOTS_API_KEY}"
      },
      "url": "https://shots-mcp.playbookmedia.io/mcp"
    }
  }
}

1. Save the file and open Cursor Settings → MCP to see shots connected.
2. Leave out headers to connect through OAuth instead; Cursor opens Shots to approve it.

VS Code (GitHub Copilot)

.vscode/mcp.json in a workspace, or MCP: Open User Configuration

{
  "inputs": [
    {
      "description": "Shots API key",
      "id": "shots-api-key",
      "password": true,
      "type": "promptString"
    }
  ],
  "servers": {
    "shots": {
      "headers": {
        "Authorization": "Bearer ${input:shots-api-key}"
      },
      "type": "http",
      "url": "https://shots-mcp.playbookmedia.io/mcp"
    }
  }
}

1. Save the file, then select Start above the shots entry. VS Code asks for the key once and stores it securely.
2. Use the tools from Copilot Chat in agent mode.

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "shots": {
      "headers": {
        "Authorization": "Bearer ${env:SHOTS_API_KEY}"
      },
      "serverUrl": "https://shots-mcp.playbookmedia.io/mcp"
    }
  }
}

1. Save the file, then refresh the MCP servers in Cascade’s plugin panel.

Gemini CLI

Terminal

gemini mcp add --transport http shots https://shots-mcp.playbookmedia.io/mcp \
  --header "Authorization: Bearer $SHOTS_API_KEY"

1. The command writes the server to ~/.gemini/settings.json. Run /mcp in Gemini CLI to check it.
2. Leave out the header and run /mcp auth shots to connect through OAuth instead.

Codex CLI

~/.codex/config.toml

[mcp_servers.shots]
url = "https://shots-mcp.playbookmedia.io/mcp"
bearer_token_env_var = "SHOTS_API_KEY"

1. Export SHOTS_API_KEY in the shell Codex runs in, then run codex mcp list to check shots.

OpenCode

opencode.json in a project, or ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shots": {
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:SHOTS_API_KEY}"
      },
      "type": "remote",
      "url": "https://shots-mcp.playbookmedia.io/mcp"
    }
  }
}

1. Run opencode mcp list to check that shots is connected.
2. Leave out headers and run opencode mcp auth shots to connect through OAuth instead.

Reference

• OpenAPI 3.1 document: the contract every tool's schema is generated from.
• Interactive API reference, with a quickstart.
• llms.txt for agents reading the site.