# MCP Tools Reference

Ang bawat MCP tool ay naka-map sa org-scoped capability. Deny-by-default ang tools: dapat isama ng API key ang
tumutugmang [MCP scope](/fil/api/mcp/#mcp-scopes), at dapat matugunan ng caller ang minimum organization
role.

## Templates

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

| Tool | Paglalarawan |
| --- | --- |
| `list_templates` | Maglista ng approved game templates na may asset schemas (`name`, size, `transparent`, `promptWrapper`) at `baseGameConfig` |
| `get_template` | Kunin ang isang template ayon sa id, kasama ang controls at config wiring hint |

Opsyonal na input sa `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 | Paglalarawan |
| --- | --- | --- |
| `list_games` | read | Maglista ng org games; opsyonal na `status` filter (`draft`, `published`, `archived`) |
| `get_game` | read | Kunin ang laro na may full flat `config` at active prizes |
| `list_game_prizes` | read | Maglista ng active prizes para sa isang laro |
| `create_game` | write | Gumawa ng draft game mula sa template; flat `config` + opsyonal na prizes |
| `update_game` | write | Mag-update ng fields; shallow-merged ang `config` |
| `set_game_status` | write | Itakda ang status sa `draft`, `published`, o `archived` |
| `set_game_prizes` | write | I-sync ang prize table (tanggalin ang `id` para gumawa; tinatanggal ang missing prizes; nililinis ng empty array ang lahat) |

Dapat umabot ang prize chance percents sa **eksaktong 100%** bawat `min_score` tier.

## Streams

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

| Tool | Scope | Paglalarawan |
| --- | --- | --- |
| `list_streams` | read | Maglista ng streams para sa organisasyon |
| `get_stream` | read | Kunin ang stream; opsyonal na `include_games` / `include_connections` |
| `create_stream` | write | Gumawa ng campaign journey (stream) |
| `update_stream` | write | Mag-update ng stream fields |

## Connections

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

| Tool | Scope | Paglalarawan |
| --- | --- | --- |
| `list_connections` | read | Maglista ng org integrations (Braze, Zapier, webhooks, …); walang raw credentials |
| `get_connection` | read | Connection detail na may `has_credentials` / `credential_keys` lang |
| `create_connection` | write | Gumawa ng integration (hal. Braze `{ api_key, rest_endpoint }`, Zapier `{ webhook_url }`) |
| `update_connection` | write | Mag-update ng name, description, o credentials kung suportado |
| `delete_connection` | write | Magtanggal ng org connection |
| `list_stream_connections` | read | Maglista ng integrations na naka-link sa stream |
| `link_stream_connection` | write | Mag-attach ng connection sa stream |
| `update_stream_connection` | write | Mag-update ng stream–connection link |
| `unlink_stream_connection` | write | Magtanggal ng stream–connection link |

:::note
Hindi suportado ang `voucher_webhook` sa pamamagitan ng MCP. Hindi kailanman ibinabalik ang provider secrets sa read responses.
:::

## Analytics Providers

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

| Tool | Scope | Paglalarawan |
| --- | --- | --- |
| `list_analytics_providers` | read | Maglista ng org analytics provider configs (public IDs only) |
| `get_analytics_provider` | read | Kunin ang isang org analytics provider |
| `create_analytics_provider` | write | Gumawa ng reusable provider (`google_analytics`, `mixpanel`, `posthog`, `amplitude`, `google_tag_manager`, `meta_pixel`) |
| `update_analytics_provider` | write | I-update ang name, config, o `is_active` |
| `delete_analytics_provider` | write | Tanggalin ang provider (cascades stream links) |
| `list_stream_analytics_providers` | read | Maglista ng providers na naka-link sa stream |
| `link_stream_analytics_provider` | write | I-attach ang org provider sa stream |
| `update_stream_analytics_provider` | write | I-update ang stream link (`is_active`, `config_override`) |
| `unlink_stream_analytics_provider` | write | Tanggalin ang stream link (nananatili ang org provider) |

Public measurement IDs / project tokens lang ang tinatanggap — never secret API keys. Tingnan ang [Analytics Providers](/fil/connections/analytics-providers/).

## Gallery

**Read scope:** `mcp:gallery:read` · **Write scope:** `mcp:gallery:write` · **Min role:** editor

| Tool | Scope | Paglalarawan |
| --- | --- | --- |
| `list_gallery_media` | read | Paginated org gallery media na may storage usage; opsyonal na `source` filter (`upload`, `generated`) |
| `delete_gallery_media` | write | Magtanggal ng gallery item ayon sa id; nabibigo na may `409` kung ginagamit pa bilang thumbnail, logo, game asset, o prize image |

Maglista ng media at suriin ang storage usage bago magtanggal. Tingnan ang [Gallery](/fil/gallery/overview/) para sa dashboard workflow.

## Vouchers

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

| Tool | Scope | Paglalarawan |
| --- | --- | --- |
| `list_voucher_sets` | read | Maglista ng voucher sets na may code stats at linked games |
| `get_voucher_set` | read | Kunin ang isang set; opsyonal na `include_vouchers` para sa indibidwal na codes |
| `create_voucher_set` | write | Gumawa ng walang laman na voucher set |
| `add_vouchers_to_set` | write | Bulk-add ng codes (uppercased; nilalaktawan ang duplicates; max 5,000 bawat call) |
| `update_org_voucher_status` | write | Itakda ang code sa `available` o `claimed` |
| `delete_org_voucher` | write | Magtanggal ng isang **available** code (hindi matatanggal ang claimed/used codes) |
| `delete_voucher_set` | write | Magtanggal ng set at cascade-delete ang codes nito |

Pagkatapos gumawa ng set at mag-import ng codes, i-link ito sa prizes gamit ang `set_game_prizes` na may
`prize_type: voucher_set` at `voucher_set_id`. Tingnan ang [Sistema ng Voucher](/fil/rewards/vouchers/).

## Reports

**Scope:** `mcp:reports:read` · **Min role:** analyst

| Tool | Paglalarawan |
| --- | --- |
| `get_org_analytics_summary` | Lightweight dashboard rollup (daily plays, totals, top game); max **90** araw |
| `get_org_report` | Detailed report JSON (parehong hugis ng Reports API nang walang CSV); max **365** araw; hanggang 100 rows ang ibinabalik ng table reports |

Tumatanggap ang `get_org_report` ng `report`, `start_date`, `end_date` (`YYYY-MM-DD`), at opsyonal na `game_id` /
`stream_id`. Mga uri ng report: `overview`, `games`, `streams`, `prizes`, `sessions`, `highscores`,
`streamScoreboard`, `ctaLeads`.

:::caution[PII sa CTA leads]
Kasama sa `ctaLeads` report ang player name, email, phone, at custom fields. Mas gusto ang least-privilege
scopes at tratuhin ang API key access nang naaayon.
:::

## AI

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

| Tool | Paglalarawan |
| --- | --- |
| `extract_brand` | Kunin ang brand identity (colors, fonts, tone, logo cues) mula sa website URL |
| `generate_funnel` | Magmungkahi ng funnel stages / stream structure mula sa brand URL o brief |
| `generate_image` | Gumawa ng **iisang** game asset gamit ang Gemini; opsyonal na transparent PNG; naiimbak sa org gallery |
| `generate_images` | Gumawa ng **hanggang 8** assets nang parallel; mas gusto ito para sa multi-asset templates |

Para sa art generation, ipasa ang `width`, `height`, `transparent`, at `prompt_wrapper` mula sa template
asset schema. Para sa `generate_images`, itakda ang `asset_key` ng bawat item sa template `asset.name`, pagkatapos
i-wire ang returned URLs sa `game.config` gamit ang `update_game` na may mga flat keys na iyon. Kapag may
higit sa 8 prompt-image assets ang template, gumawa muna ng laro na may placeholders, pagkatapos gumawa nang batches.

## Sessions

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

| Tool | Paglalarawan |
| --- | --- |
| `create_play_session` | Mag-mint ng one-time play session token para sa `game_id` o `stream_id` (pareho ng REST create-session API) |

Opsyonal na inputs: `external_ref`, `metadata`, `expires_in_minutes` (max 7 araw).

Tingnan ang [Session Tokens](/fil/api/session-tokens/) para sa player URL patterns at lifecycle.

## Buod ng Role Requirements

| Min role | Tools |
| --- | --- |
| **viewer** | Template, game/stream, at voucher read tools |
| **analyst** | Report tools |
| **editor** | Game/stream write, gallery, voucher write, AI, session minting |
| **admin** | Lahat ng connection at analytics provider tools |

Minamana ng API keys ang membership model ng organisasyon para sa role checks kapag ginagamit sa pamamagitan ng MCP.
Nalalapat pa rin ang resource allowlists sa key.

Ang parehong capabilities ang nagpapagana sa in-app [Assistant](/fil/assistant/overview/) (authenticated bilang iyong signed-in
user, hindi API key).