# MCP Tools Reference

Every MCP tool maps to an org-scoped capability. Tools are deny-by-default: the API key must include
the matching [MCP scope](/api/mcp/#mcp-scopes), and the caller must meet the minimum organization
role.

## Templates

**Scope:** `mcp:templates:read` · **Min role:** viewer

| Tool | Description |
| --- | --- |
| `list_templates` | List approved game templates with asset schemas (`name`, size, `transparent`, `promptWrapper`) and `baseGameConfig` |
| `get_template` | Get one template by id, including controls and a config wiring hint |

Optional input on `list_templates`: `category` (case-insensitive substring filter).

## Games & Prizes

**Read scope:** `mcp:games:read` · **Write scope:** `mcp:games:write` · **Min role:** viewer (read) / editor (write)

| Tool | Scope | Description |
| --- | --- | --- |
| `list_games` | read | List org games; optional `status` filter (`draft`, `published`, `archived`) |
| `get_game` | read | Get a game with full flat `config` and active prizes |
| `list_game_prizes` | read | List active prizes for a game |
| `create_game` | write | Create a draft game from a template; flat `config` + optional prizes |
| `update_game` | write | Update fields; `config` is shallow-merged |
| `set_game_status` | write | Set status to `draft`, `published`, or `archived` |
| `set_game_prizes` | write | Sync the prize table (omit `id` to create; missing prizes are deleted; empty array clears all) |

Prize chance percents must total **exactly 100%** per `min_score` tier.

## Streams

**Read scope:** `mcp:streams:read` · **Write scope:** `mcp:streams:write` · **Min role:** viewer (read) / editor (write)

| Tool | Scope | Description |
| --- | --- | --- |
| `list_streams` | read | List streams for the organization |
| `get_stream` | read | Get a stream; optional `include_games` / `include_connections` |
| `create_stream` | write | Create a campaign journey (stream) |
| `update_stream` | write | Update stream fields |

## Connections

**Read scope:** `mcp:connections:read` · **Write scope:** `mcp:connections:write` · **Min role:** admin

| Tool | Scope | Description |
| --- | --- | --- |
| `list_connections` | read | List org integrations (Braze, Zapier, webhooks, …); no raw credentials |
| `get_connection` | read | Connection detail with `has_credentials` / `credential_keys` only |
| `create_connection` | write | Create an integration (e.g. Braze `{ api_key, rest_endpoint }`, Zapier `{ webhook_url }`) |
| `update_connection` | write | Update name, description, or credentials where supported |
| `delete_connection` | write | Delete an org connection |
| `list_stream_connections` | read | List integrations linked to a stream |
| `link_stream_connection` | write | Attach a connection to a stream |
| `update_stream_connection` | write | Update a stream–connection link |
| `unlink_stream_connection` | write | Remove a stream–connection link |

:::note
`voucher_webhook` is not supported via MCP. Provider secrets are never returned in read responses.
:::

## AI

**Scope:** `mcp:ai` · **Min role:** editor

| Tool | Description |
| --- | --- |
| `extract_brand` | Extract brand identity (colors, fonts, tone, logo cues) from a website URL |
| `generate_funnel` | Suggest funnel stages / stream structure from a brand URL or brief |
| `generate_image` | Generate a game asset with Gemini; optional transparent PNG; stores in org blob storage |

For art generation, pass `width`, `height`, `transparent`, and `prompt_wrapper` from the template
asset schema, then wire the returned `url` into `game.config` with `update_game` using the asset's
flat key name.

## Sessions

**Scope:** `mcp:sessions:write` · **Min role:** editor

| Tool | Description |
| --- | --- |
| `create_play_session` | Mint a one-time play session token for a `game_id` or `stream_id` (same as the REST create-session API) |

Optional inputs: `external_ref`, `metadata`, `expires_in_minutes` (max 7 days).

See [Session Tokens](/api/session-tokens/) for the player URL patterns and lifecycle.

## Role Requirements Summary

| Min role | Tools |
| --- | --- |
| **viewer** | Template and game/stream read tools |
| **editor** | Game/stream write, AI, session minting |
| **admin** | All connection tools |

API keys inherit the organization's membership model for role checks when used through MCP.
Resource allowlists on the key still apply.