---
title: "连接你的 AI（MCP）"
description: "Yumina 在 yumina.io/mcp 有一个 MCP 服务器。把 Claude、ChatGPT、Cursor、Claude Code 或 Codex 连到你的账号，它就能在 Studio 里实时读、改、试玩你的卡。"
---

# 连接你的 AI

Yumina 在 `https://yumina.io/mcp` 有一个 [MCP](https://modelcontextprotocol.io) 服务器。把它加进你平时用的 AI 工具，登录一次，那个 AI 就能打开你的卡，写设定、变量、行为和界面代码，生图和试玩，每一处改动都实时出现在你的画布上。它不能发布。那一下永远由你来点。

Studio 里的创作助手不用任何设置就能做同样的事。想用自己的模型、自己的订阅，或者一个在终端里持续干活的 agent 时，再连接你自己的 AI。

## 快速开始

1. 打开画布右上角的 ⋮ 菜单，点 **连接你的 AI**。卡要先保存过一次。
2. 选你的工具。弹窗会显示它的步骤，归根到底都是上面那个地址。
3. 在打开的 Yumina 页面上点 **允许**。
4. 给你的 AI 发第一句话。弹窗会察觉到连接，并告诉你。

```text
Use Yumina to open my card "Mushroom Tavern" and tell me what's in it right now.
```

## 各个客户端

### Claude

桌面版或网页版。打开 Settings → Connectors → **Add custom connector**，名字填 Yumina，粘贴地址，点 Continue，再点 Add。点 Connect，然后在 Yumina 页面上点允许。

### ChatGPT 和 Codex

Settings → Plugins → Add → **Add MCP server**。名字填 yumina，选 Streamable HTTP，粘贴地址，Save。登录 Yumina，点允许。

### Cursor

点弹窗里的 **添加到 Cursor**，或者把下面这段加进 `.cursor/mcp.json`，然后登录 Yumina，点允许：

```json
{ "mcpServers": { "yumina": { "url": "https://yumina.io/mcp" } } }
```

### Claude Code

```bash
claude mcp add --transport http yumina https://yumina.io/mcp
```

然后在 Claude Code 里输入 `/mcp`，选 yumina，Authenticate，在浏览器里点允许。

### Codex CLI

```bash
codex mcp add yumina --url https://yumina.io/mcp
codex mcp login yumina
```

然后打开 `~/.codex/config.toml`，在 `[mcp_servers.yumina]` 下面加一行，因为 Codex 默认只给工具 60 秒，而试玩或生图要更久：

```toml
tool_timeout_sec = 300
```

### DeepSeek Harness

它暂时不能登录，所以弹窗里它那一栏会给你打开的这张卡生成一个令牌，给你一份 `yumina.yml` 保存，再给你一行要运行的命令：

```bash
npx @deepseek-ai/dsh web --patch yumina.yml
```

这个令牌只能碰这一张卡，90 天后失效。

### 其它工具

它不能登录的话，打开弹窗里的 **无法登录？给这张卡生成令牌**。把它显示的地址和 Authorization 请求头填进你的工具。令牌只显示一次。

## 使用示例

```text
Add a sly merchant called Vex who talks in riddles and has trust issues.
```

```text
Make a hunger variable that drops over time. When it hits zero, the player dies.
```

```text
Build a dark fantasy interface with health, mana and inventory slots.
```

```text
Go through the sticky notes on my card and make every change they ask for.
```

```text
Playtest five turns as a cautious player and tell me which variables never moved.
```

```text
Check the card for anything wired wrong and fix it.
```

## 可用的工具

| 任务 | 工具 |
|---|---|
| 找你的卡 | `list_my_cards`、`create_card` |
| 读一张卡 | `get_world`、`read_entities`、`grep_world`、`list_assets`、`read_ui_doc`、`load_skill` |
| 免费检查 | `validate_world`、`analyze_token_cost`、`simulate_behaviors` |
| 写故事 | `write_entry`、`write_variable`、`write_behavior`、`write_worldbook`、`write_audio`、`write_scene_image`、`write_note`、`update_settings`、`set_card_name`、`delete_entities` |
| 搭界面 | `write_custom_ui`、`edit_custom_ui`、`edit_ui_doc`、`set_ui_knobs` |
| 试一试 | `playtest`，一次最多 10 步，以及 `screenshot_ui` |
| 生图 | `generate_image`、`set_cover` |

大多数工具带一个 `variant`，所以它可以改一张卡的其它语言版本。它会读你的便签，也知道每张贴在哪。服务器会告诉每个 AI 先从 `get_world` 开始，`delete_entities` 标记为破坏性操作，所以尊重这个提示的客户端会先问你。

## 费用

读、写、检查都免费。试玩的步数、带步数的截图和生图按正常价格扣蘑菇币，和你自己点一样，失败会退回。

## 安全

- **任何配置文件里都没有密码。** 登录用的是 OAuth 2.1 加 PKCE。AI 拿到的是一个短期令牌，只有「卡」这一项权限，没有别的，授权页会列出它具体覆盖什么。
- **它不能发布，也碰不到你的账号。** 在已发布的卡上，它的改动会以未发布的修改等着，直到你提交。碰不到余额、密码或设置。
- **每次改动前都有一个存档点。** ⋮ → 改动记录 里会显示「Before: Claude」，或者是哪个 AI，你可以回退到那一刻。每个 AI 每 15 分钟最多一个。
- **上限能拦住失控的 agent。** 每小时 30 回合试玩、20 张图和 30 张截图，每天 20 张新卡。

你还是应该：

- **发布前读一遍它写的东西**，和用创作助手一样。
- **断开不再用的。** 弹窗里的 已连接的 AI，或者 设置 → 账户 → 已连接的应用，会列出每一个和它最近使用的时间。断开它就立刻失去访问权限。卡的令牌也在那里列出，用同样的方式作废。
- **干净地换账号。** 断开，在浏览器里退出 Yumina，登录另一个账号，再连一次。Codex CLI 的话，先运行 `codex mcp logout yumina`，再运行 `codex mcp login yumina`。

## 没有连接器的话

你的工具完全不支持 MCP 的话，把[世界文件格式](/zh/world-spec/)给它。它写出卡的 JSON，你再导入。

## 相关

- [创作助手](./studio-ai.md)
- [世界文件格式](/zh/world-spec/)
