# MCP Server

Nag-e-expose ang DailyPlay ng remote **MCP (Model Context Protocol)** server para makagawa ang AI agents — Cursor, Claude,
at iba pang MCP clients — ng mga laro, pamahalaan ang streams, gumawa ng assets, pamahalaan ang gallery media at
voucher sets, magbasa ng analytics reports, at mag-mint ng play sessions para sa iyong organisasyon.

:::note[Business Tier Required]
Gumagamit ang MCP access ng organization API keys, na available sa **Business tier** o mas mataas.
:::

## Endpoint

| | |
| --- | --- |
| **URL** | `https://app.dailyplay.ai/api/mcp` |
| **Transport** | Streamable HTTP |
| **Auth** | Bearer API key (`dpk_…`) |

Naka-publish ang discovery metadata sa:

```
https://app.dailyplay.ai/.well-known/oauth-protected-resource
```

## Bago Ka Magsimula

1. Gumawa ng [API key](/fil/api/api-keys/) sa **Connect → API Keys**
2. I-enable ang **MCP scopes** na kailangan ng iyong agent (iwanang walang laman para sa session-token minting lang)
3. Kopyahin ang key value na ipinakita nang isang beses sa creation time (`dpk_…`)

Nag-a-authenticate ang DailyPlay gamit ang **Bearer API key**, hindi OAuth. Sa mga client na nag-aalok ng pareho, piliin
ang header / API-key auth at i-skip ang sign-in flow.

## Client Setup

### Claude Desktop, Claude.ai, at Cowork

Gumamit ng **custom connector** (remote MCP). Naabot ng Claude ang server mula sa cloud ng Anthropic — dapat
publicly reachable ang endpoint.

1. Buksan ang **Customize → Connectors** (Team/Enterprise owners: **Organization settings → Connectors**)
2. I-click ang **Add custom connector** (o **Add → Custom → Web**)
3. Itakda ang:
   - **Name:** `DailyPlay` (o anumang label)
   - **MCP server URL:** `https://app.dailyplay.ai/api/mcp`
4. Sa authentication, piliin ang **No sign-in** (hindi pa gumagamit ang DailyPlay ng OAuth)
5. Magdagdag ng **request header**:
   - Header: `Authorization`
   - Value: `Bearer dpk_YOUR_KEY` (isama ang `Bearer ` prefix at ang space)
6. I-save, pagkatapos i-enable ang connector para sa chat sa pamamagitan ng **+** menu → **Connectors**

:::note[Request headers availability]
Ang request-header auth para sa custom connectors ay rolling out at maaaring hindi lumabas para sa bawat plan o
organization. Kung hindi mo nakikita ang **Request headers**, gamitin ang [stdio bridge](#claude-desktop-local-config)
sa ibaba, o mag-set up ng [Claude Code](#claude-code) / [Cursor](#cursor) sa halip.
:::

#### Claude Desktop local config

Ang `claude_desktop_config.json` ay tumatanggap lang ng **stdio** servers. Para ituro ang Desktop sa remote URL
ng DailyPlay, mag-bridge gamit ang [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) (kailangan ang Node.js 18+):

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "dailyplay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.dailyplay.ai/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer dpk_YOUR_KEY"
      }
    }
  }
}
```

I-restart ang Claude Desktop pagkatapos mag-save. Huwag maglagay ng bare `url` field sa file na ito — hindi pinapansin ng Desktop
ang remote HTTP entries doon.

### Claude Code

```bash
claude mcp add --transport http dailyplay https://app.dailyplay.ai/api/mcp \
  --header "Authorization: Bearer dpk_YOUR_KEY"
```

Mas gusto ang `claude mcp add` (user o local scope) kaysa sa hand-editing ng `.mcp.json` para mailapat ang headers
sa bawat request. Equivalent JSON:

```json
{
  "mcpServers": {
    "dailyplay": {
      "type": "http",
      "url": "https://app.dailyplay.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dpk_YOUR_KEY"
      }
    }
  }
}
```

### Cursor

1. Buksan ang **Cursor Settings → MCP** (o i-edit ang config file)
2. Magdagdag ng remote server entry:

**Project:** `.cursor/mcp.json`  
**Global:** `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "dailyplay": {
      "url": "https://app.dailyplay.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dpk_YOUR_KEY"
      }
    }
  }
}
```

Maaari mong panatilihing wala ang key sa file gamit ang env interpolation:

```json
"Authorization": "Bearer ${env:DAILYPLAY_API_KEY}"
```

I-enable ang server sa ilalim ng **Available Tools**, pagkatapos hilingin sa agent na maglista ng templates o games para
kumpirmahin ang connection.

### Iba pang MCP clients

Anumang client na sumusuporta ng **Streamable HTTP** remote MCP ay gumagana sa parehong paraan:

| Setting | Value |
| --- | --- |
| URL | `https://app.dailyplay.ai/api/mcp` |
| Auth header | `Authorization: Bearer dpk_…` |
| Alternative header | `x-api-key: dpk_…` |

Kung stdio lang ang sinusuportahan ng client, gamitin ang [`mcp-remote`](#claude-desktop-local-config) bridge
pattern mula sa Claude Desktop section.

## Beripikahin ang Connection

Pagkatapos kumonekta, tanungin ang agent ng isang bagay na nangangailangan ng tool, halimbawa:

- “List DailyPlay game templates”
- “List games in my organization”

Kung nawawala ang tools o nabigo ang bawat call na may `401` / scope errors:

- Kumpirmahin na nagsisimula ang key sa `dpk_` at nakopya nang buo
- Kumpirmahin na naka-enable ang kinakailangang [MCP scopes](#mcp-scopes) sa key
- Kumpirmahin na **enabled** ang connector o MCP server para sa kasalukuyang chat
- I-restart ang client pagkatapos mag-edit ng config files

## Authentication

Nag-a-authenticate ang MCP tools gamit ang parehong organization API keys na ginagamit para sa [session tokens](/fil/api/session-tokens/).

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer dpk_…` |
| o `x-api-key` | `dpk_…` |

Kinukuha ang organisasyon mula sa key — hindi kailanman nagbibigay ang clients ng `org_id` para sa mutations.

:::caution[Scopes are deny-by-default]
Ang API keys na **walang MCP scopes** ay maaari lang mag-mint ng play-session tokens sa pamamagitan ng REST API. Hindi sila
maaaring tumawag ng MCP tools hanggang i-enable mo ang scopes na kailangan mo.
:::

## MCP Scopes

I-enable ang scopes kapag gumagawa o nag-e-edit ng key:

| Scope | Ano ang nai-unlock |
| --- | --- |
| `mcp:templates:read` | Maglista at mag-inspect ng game templates |
| `mcp:games:read` | Maglista at magbasa ng games at prizes |
| `mcp:games:write` | Gumawa/mag-update ng games, status, at prizes |
| `mcp:streams:read` | Maglista at magbasa ng streams |
| `mcp:streams:write` | Gumawa at mag-update ng streams |
| `mcp:connections:read` | Maglista ng org integrations (walang raw credentials) |
| `mcp:connections:write` | Gumawa ng integrations at i-link ang mga ito sa streams |
| `mcp:analytics_providers:read` | Maglista ng org analytics providers at stream links |
| `mcp:analytics_providers:write` | Gumawa ng analytics providers at i-link ang mga ito sa streams |
| `mcp:gallery:read` | Maglista ng org gallery media at storage usage |
| `mcp:gallery:write` | Magtanggal ng gallery media |
| `mcp:vouchers:read` | Maglista at magbasa ng voucher sets |
| `mcp:vouchers:write` | Gumawa at pamahalaan ang voucher sets at codes |
| `mcp:reports:read` | Magbasa ng org analytics at reports |
| `mcp:ai` | Brand extract, funnel suggestions, image generation |
| `mcp:sessions:write` | Mag-mint ng one-time play session tokens |

Tingnan ang buong [MCP tools reference](/fil/api/mcp-tools/) para sa bawat tool at ang required scope nito.

## Karaniwang Agent Workflow

Isang karaniwang flow para mag-brand ng bagong laro mula sa template:

1. `list_templates` / `get_template` — basahin ang asset schemas (`name`, size, `transparent`, `promptWrapper`)
2. `create_game` na may placeholder image URLs kapag maraming assets ang template
3. `generate_images` (hanggang 8 bawat call) — mas gusto ito kaysa sa paulit-ulit na `generate_image` calls; chroma-keyed ang transparent assets
4. `update_game` — i-wire ang returned URLs sa **flat** `config` na naka-key sa `asset.name` (hal. `character`, `obstacle`)
5. Opsyonal na `create_voucher_set` / `add_vouchers_to_set`, pagkatapos `set_game_prizes` na may `prize_type: voucher_set`
6. `set_game_status` — i-publish kapag handa na

:::tip[Flat config keys]
**Huwag** i-nest ang image URLs sa ilalim ng `config.assets`. Gamitin ang template asset `name` bilang top-level key
sa `config`. Shallow-merge ang `config` ng `update_game`, kaya maaari mong i-patch ang isang asset nang hindi nabubura ang iba.
:::

Mas gusto ang in-app [Assistant](/fil/assistant/overview/) kapag gusto mo ang parehong capabilities nang hindi nagsi-set up ng
external MCP client (available sa lahat ng subscription tiers).

## Braze / Connections Example

Nangangailangan ang connection tools ng **admin** (o owner) role sa organisasyon ng key.

1. `create_stream` (`mcp:streams:write`)
2. `create_connection` na may `provider: "braze"` at `credentials: { api_key, rest_endpoint }`
3. `link_stream_connection` na may bagong `stream_id` at `connection_id`

Write-only ang credential values — hindi kailanman ibinabalik ng list/get responses ang raw secrets.

## Analytics Providers Example

Nangangailangan din ang analytics provider tools ng **admin** (o owner) role. Nagko-configure ang mga ito ng **client-side** SDKs (hiwalay sa Connections). Tingnan ang [Analytics Providers](/fil/connections/analytics-providers/).

1. `create_analytics_provider` na may `provider` (hal. `"google_analytics"`) at public `config` (hal. `{ measurement_id: "G-…" }`)
2. `link_stream_analytics_provider` na may `stream_id` at `analytics_provider_id`
3. Optional `config_override` sa link; pinapanatili ng `unlink_stream_analytics_provider` ang org provider

## Mga Nota sa Seguridad

- Mas gusto ang **least-privilege scopes** — i-enable lang ang tools na kailangan ng iyong agent
- Pagsamahin ang MCP scopes sa [game/stream allowlists](/fil/api/api-keys/#key-scoping) para limitahan kung aling resources ang maaaring hawakan ng key
- I-rotate o i-revoke ang keys mula sa dashboard kung na-expose ang key
- Nalalapat din ang rate limits sa API key sa MCP tool calls

## Mga Susunod na Hakbang

- [MCP Tools Reference](/fil/api/mcp-tools/) — bawat tool, scope, at role
- [In-app Assistant](/fil/assistant/overview/) — parehong capabilities sa loob ng DailyPlay dashboard
- [API Keys](/fil/api/api-keys/) — gumawa ng keys at pamahalaan ang MCP scopes
- [Session Tokens](/fil/api/session-tokens/) — one-time play access nang walang MCP