# MCP 服务器

DailyPlay 公开远程 **MCP（Model Context Protocol）** 服务器，以便 AI 智能体 — Cursor、Claude 及其他 MCP 客户端 — 代表您的组织创建游戏、管理 streams、生成素材、管理图库媒体与兑换码集、阅读分析报告并生成游玩会话。

:::note[需要 Business 层级]
MCP 访问使用组织 API keys，适用于 **Business 层级**或更高。
:::

## 端点

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

发现元数据发布于：

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

## 开始之前

1. 在 **Connect → API Keys** 中创建 [API key](/zh/api/api-keys/)
2. 启用智能体所需的 **MCP scopes**（留空则仅用于会话令牌生成）
3. 复制创建时显示一次的密钥值（`dpk_…`）

DailyPlay 使用 **Bearer API key** 进行身份验证，而非 OAuth。在同时提供两者的客户端中，选择 header / API-key 认证并跳过登录流程。

## 客户端设置

### Claude Desktop、Claude.ai 与 Cowork

使用**自定义连接器**（远程 MCP）。Claude 从 Anthropic 云访问服务器 — 端点必须可公开访问。

1. 打开 **Customize → Connectors**（Team/Enterprise 所有者：**Organization settings → Connectors**）
2. 点击 **Add custom connector**（或 **Add → Custom → Web**）
3. 设置：
   - **Name：** `DailyPlay`（或任意标签）
   - **MCP server URL：** `https://app.dailyplay.ai/api/mcp`
4. 在身份验证下，选择 **No sign-in**（DailyPlay 尚未使用 OAuth）
5. 添加 **request header**：
   - Header：`Authorization`
   - Value：`Bearer dpk_YOUR_KEY`（包含 `Bearer ` 前缀与空格）
6. 保存，然后通过 **+** 菜单 → **Connectors** 为聊天启用连接器

:::note[Request headers 可用性]
自定义连接器的 request-header 认证正在逐步推出，可能并非在每个计划或组织中都可见。若看不到 **Request headers**，请使用下方的 [stdio bridge](#claude-desktop-local-config)，或改用 [Claude Code](#claude-code) / [Cursor](#cursor)。
:::

#### Claude Desktop 本地配置

`claude_desktop_config.json` 仅接受 **stdio** 服务器。要将 Desktop 指向 DailyPlay 的远程 URL，请使用 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 桥接（需要 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"
      }
    }
  }
}
```

保存后重启 Claude Desktop。不要在此文件中放置裸 `url` 字段 — Desktop 会忽略其中的远程 HTTP 条目。

### Claude Code

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

优先使用 `claude mcp add`（用户或本地范围）而非手动编辑 `.mcp.json`，以便每次请求都应用 headers。等效 JSON：

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

### Cursor

1. 打开 **Cursor Settings → MCP**（或编辑配置文件）
2. 添加远程服务器条目：

**项目：** `.cursor/mcp.json`  
**全局：** `~/.cursor/mcp.json`

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

您可以使用环境变量插值将密钥排除在文件之外：

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

在 **Available Tools** 下启用服务器，然后请智能体列出模板或游戏以确认连接。

### 其他 MCP 客户端

任何支持 **Streamable HTTP** 远程 MCP 的客户端都以相同方式工作：

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

若客户端仅支持 stdio，请使用 Claude Desktop 部分中的 [`mcp-remote`](#claude-desktop-local-config) 桥接模式。

## 验证连接

连接后，请智能体执行需要工具的操作，例如：

- 「列出 DailyPlay 游戏模板」
- 「列出我组织中的游戏」

若工具缺失或每次调用都因 `401` / 范围错误失败：

- 确认密钥以 `dpk_` 开头且已完整复制
- 确认密钥上已启用所需的 [MCP scopes](#mcp-scopes)
- 确认当前聊天已**启用**连接器或 MCP 服务器
- 编辑配置文件后重启客户端

## Authentication

MCP 工具使用与 [session tokens](/zh/api/session-tokens/) 相同的组织 API keys 进行身份验证。

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

组织取自密钥 — 客户端无需为变更操作提供 `org_id`。

:::caution[范围默认为拒绝]
**无 MCP scopes** 的 API keys 只能通过 REST API 生成游玩会话令牌。在启用所需范围之前，它们无法调用 MCP 工具。
:::

## MCP Scopes

创建或编辑密钥时启用范围：

| 范围 | 解锁内容 |
| --- | --- |
| `mcp:templates:read` | 列出并检查游戏模板 |
| `mcp:games:read` | 列出并读取游戏与奖品 |
| `mcp:games:write` | 创建/更新游戏、状态与奖品 |
| `mcp:streams:read` | 列出并读取 streams |
| `mcp:streams:write` | 创建并更新 streams |
| `mcp:connections:read` | 列出组织集成（无原始凭据） |
| `mcp:connections:write` | 创建集成并将其链接到 streams |
| `mcp:analytics_providers:read` | 列出组织分析提供商与 stream 链接 |
| `mcp:analytics_providers:write` | 创建分析提供商并将其链接到 streams |
| `mcp:gallery:read` | 列出组织图库媒体与存储用量 |
| `mcp:gallery:write` | 删除图库媒体 |
| `mcp:vouchers:read` | 列出并读取兑换码集 |
| `mcp:vouchers:write` | 创建并管理兑换码集与代码 |
| `mcp:reports:read` | 阅读组织分析与报告 |
| `mcp:ai` | 品牌提取、漏斗建议、图片生成 |
| `mcp:sessions:write` | 生成一次性游玩会话令牌 |

每个工具及其所需范围见完整 [MCP 工具参考](/zh/api/mcp-tools/)。

## 典型智能体工作流

从模板为新游戏做品牌化的常见流程：

1. `list_templates` / `get_template` — 读取素材模式（`name`、尺寸、`transparent`、`promptWrapper`）
2. 当模板有许多素材时，用占位图片 URL 调用 `create_game`
3. `generate_images`（每次调用最多 8 张）— 优先于此而非重复调用 `generate_image`；透明素材会进行色度键处理
4. `update_game` — 将返回的 URL 写入以 `asset.name` 为键的**扁平** `config`（例如 `character`、`obstacle`）
5. （可选）`create_voucher_set` / `add_vouchers_to_set`，然后用 `prize_type: voucher_set` 调用 `set_game_prizes`
6. `set_game_status` — 准备好后发布

:::tip[扁平 config 键]
**不要**将图片 URL 嵌套在 `config.assets` 下。使用模板素材 `name` 作为 `config` 上的顶级键。`update_game` 对 `config` 进行浅合并，因此您可以修补一个素材而不清除其余内容。
:::

若希望无需设置外部 MCP 客户端即可使用相同能力（所有订阅层级均可用），请优先使用应用内 [Assistant](/zh/assistant/overview/)。

## Braze / Connections 示例

连接工具需要密钥所属组织上的 **admin**（或 owner）角色。

1. `create_stream`（`mcp:streams:write`）
2. 使用 `provider: "braze"` 与 `credentials: { api_key, rest_endpoint }` 调用 `create_connection`
3. 使用新的 `stream_id` 与 `connection_id` 调用 `link_stream_connection`

凭据值为只写 — list/get 响应从不返回原始密钥。

## 分析提供商示例

分析提供商工具同样需要 **admin**（或 owner）角色。它们配置**客户端** SDK（与 Connections 不同）。见[分析提供商](/zh/connections/analytics-providers/)。

1. 使用 `provider`（如 `"google_analytics"`）与公开 `config`（如 `{ measurement_id: "G-…" }`）调用 `create_analytics_provider`
2. 使用 `stream_id` 与 `analytics_provider_id` 调用 `link_stream_analytics_provider`
3. 可选链接上的 `config_override`；`unlink_stream_analytics_provider` 会保留组织提供商

## 安全说明

- 优先使用**最小权限范围** — 仅启用智能体所需的工具
- 将 MCP scopes 与 [游戏/stream 白名单](/zh/api/api-keys/#key-scoping) 结合，限制密钥可触及的资源
- 若密钥泄露，从面板轮换或撤销密钥
- API key 上的速率限制也适用于 MCP 工具调用

## 下一步

- [MCP 工具参考](/zh/api/mcp-tools/) — 每个工具、范围与角色
- [应用内助手](/zh/assistant/overview/) — DailyPlay 面板内的相同能力
- [API Keys](/zh/api/api-keys/) — 创建密钥并管理 MCP scopes
- [Session Tokens](/zh/api/session-tokens/) — 无需 MCP 的一次性游玩访问