# 连接 iMario MCP 服务器

> 授权连接或创建工作区密钥，配置好客户端，运行调研之前先确认能正常访问。

Source: https://imario.ai/zh/docs/agent-setup/mcp

## 开始之前
服务器地址是 `https://mcp.imario.ai/mcp`。Settings > MCP & API 页面上也能看到这个地址，旁边带复制按钮。

客户端必须支持 Streamable HTTP。认证方式有两种，用哪一种取决于客户端，跟你的账号无关：

- **授权连接**。ChatGPT、Claude 应用、Claude Code、Codex、Cursor 和 VS Code 会把你带到 iMario，你在那里登录、选好工作区，然后确认授权。全程不用复制任何东西。
- **使用 API 密钥**。没法打开浏览器的程序，比如定时任务、CI 或你自己开发的智能体，就用工作区的 API 密钥，在 **Settings > MCP & API** 里获取。

不管用哪种方式，连接都以创建者本人的身份操作，而且只限一个工作区。工作区成员身份和角色权限照样适用；连接一旦撤销，或者持有人离开工作区，认证就失效。查看者只有读取权限，不能借此发起调研。

两种方式都不自带预算。已连接的应用最多能花多少，由整个工作区共用的一个每日上限决定，在 **Settings > MCP & API** 的 **Daily limit** 里设置。每个已连接的应用和 API 密钥旁边，都显示着最近 30 天花了多少。

在 Claude Code、Codex 或 Cursor 里，整个配置过程都可以交给智能体：粘贴 `Connect iMario to this agent: imario.ai/SKILL.md` 就行。智能体会运行第 2 步里的命令，再装上[配套技能](https://imario.ai/zh/docs/agent-setup/install-skill)；第 1a 步的授权，还是要你自己来。

## 1a. 授权连接（ChatGPT、Claude、Claude Code、Codex、VS Code）
1. 在应用里添加一个连接器，填入上面的服务器地址。如果用的是 Claude Code 或 Codex，就运行第 2 步里的命令。
2. 应用会自动找到授权地址，并表明自己的身份：要么注册为客户端，要么指向它自己的客户端元数据文档。随后页面跳转到 iMario。
3. 还没登录的话先登录，然后选择允许这个应用访问的工作区，点击 **Approve**。
4. 页面跳回应用，连接就建好了。

两个聊天应用添加连接器的位置如下：

| 应用 | 操作路径 |
|---|---|
| ChatGPT | 进入 **Settings > Security and login**，打开 **Developer mode**。再进入 **Settings > Plugins**，点击 **+**，名称填 iMario，服务器 URL 填 `https://mcp.imario.ai/mcp`，然后点击 **Create**。浏览器里出现授权提示时，确认授权这次连接。 |
| claude.ai 和 Claude 桌面应用 | 进入 **Customize > Connectors**，点击 **+**，再点 **Add custom connector**，填入 `https://mcp.imario.ai/mcp`，点击 **Add**。如果是 Team 或 Enterprise 套餐，先由 Owner 在 **Organization settings > Connectors > Add > Custom > Web** 里添加，再由每位成员在 **Customize > Connectors** 里点击 **Connect**。在对话里点 **+ > Connectors** 把它打开。 |

把 `Connect iMario to this agent: imario.ai/SKILL.md` 贴进这两个应用，并不会添加连接器：它们只会读完页面再作答，不会照着去做。这一行是给 Claude Code、Codex 和 Cursor 用的。其他支持 Streamable HTTP 的通用 MCP 客户端，可以按下文的方式，用服务器地址加 API 密钥接入；如果客户端支持浏览器授权，也可以用它自带的 OAuth 授权界面。

连接建好后，会以应用名称出现在 **Settings > MCP & API** 里。在那里点垃圾桶图标就能断开连接：应用从下一次请求起就访问不了工作区，想再用就得重新授权。

## 1b. 生成 API 密钥
1. 打开工作区，进入 **Settings > MCP & API**。
2. 以所有者或管理员身份，在 **API keys** 下点击 **Generate key**。
3. 趁密钥还显示在屏幕上，把它复制下来。密钥只显示这一次，之后页面上只会显示开头几个字符。

每个工作区只有一个 API 密钥。点击 **Regenerate** 会替换掉它：旧密钥从下一次请求起失效，新密钥立即可用。凡是用过旧密钥的地方，都要换成新密钥。

把密钥存在客户端的本地配置或凭证管理功能里。不要把真实密钥写进会提交到仓库的项目文件，也不要贴到聊天消息里。

## 2. 配置客户端
### Claude Code```bash
claude mcp add --transport http imario YOUR_MCP_ENDPOINT
```

然后在 Claude Code 里运行 `/mcp`，选中 `imario`，再选择 **Authenticate**。浏览器会打开第 1a 步里的授权页面。配置作用域和移除方法，参见 Claude Code 的 [MCP 说明](https://code.claude.com/docs/en/mcp)。

### Codex```bash
codex mcp add imario --url YOUR_MCP_ENDPOINT
codex mcp login imario
```

第二条命令会在浏览器里打开授权页面。详见 [Codex 的 MCP 说明](https://developers.openai.com/codex/mcp)。

`claude mcp add` 和 `codex mcp add` 注册的都是远程服务器，不会在本地装任何 iMario 进程。ChatGPT、claude.ai 这类在自己设置里连接的应用，不用另做配置，做完第 1a 步就全部设好了。

### VS Code
MCP 服务器从哪里配置，以你安装的 VS Code 实际提供的入口为准。在那里添加一个名为 `imario` 的服务器，填入 Streamable HTTP 端点。如果客户端提供浏览器授权流程，就选它；如果要求填写密钥，就用 `Authorization: Bearer YOUR_IMARIO_KEY`，并把密钥存进客户端的凭证存储。

### 其他 MCP 客户端
如果是通用的 MCP 客户端，把 `https://mcp.imario.ai/mcp` 添加为一个 Streamable HTTP 服务器，命名为 `imario`。客户端支持 OAuth 授权，就走完授权流程；不支持，就把工作区 API 密钥配置成授权请求头。之后先列出工具和人群，再去预估或运行调研。

### 使用密钥
配置一个名为 `imario` 的服务器，填写所用部署的 URL，选择 Streamable HTTP，再添加 `Authorization: Bearer YOUR_IMARIO_KEY`。服务端也接受 `X-Imario-Key`。各家客户端的配置文件格式不一样，不要把一个客户端的 JSON 原封不动地复制到另一个客户端的设置里。

不想登录的话，Claude Code 也可以直接用密钥：

```bash
claude mcp add --transport http imario YOUR_MCP_ENDPOINT --header "Authorization: Bearer YOUR_IMARIO_KEY"
```

## 发送自己的图片和问卷
创意测试给受访者看的是真实的图片。iMario 先用应用直接提供的附件；没有附件、但助手读得到文件时，就自动上传。只有这两条路都走不通，或者自动上传失败时，才需要你再选一次图片：

| 你用的环境 | 处理方式 |
|---|---|
| 支持文件输入的 ChatGPT | 应用直接把附件交给 iMario，不用再选一次文件。 |
| Codex、Claude Code，或其他能访问文件和网络的客户端 | 助手会自动上传它能读取的附件，不会弹出手动上传的卡片。 |
| 不支持自动传输的客户端，或上传失败之后 | 助手可以打开一张 iMario 卡片。选好图片后点击 **Upload image**；如果卡片里带着你的调研，就点击 **Start study**。 |
| 不支持卡片的客户端 | 助手可以给你一个一次性链接，让你在浏览器里上传图片。 |

生成了上传链接，或者算出了调研价格，都不代表图片已经传到了。助手应该等 iMario 确认收到之后，才告诉你上传成功。如果卡片已经把图片传上去了，调研却没能启动，在卡片里重试时会沿用这张图片。

claude.ai 上的助手还能从代码执行环境上传图片，前提是这个环境获准访问 iMario。要允许访问，在 **Settings > Capabilities > Code execution and file creation > Additional allowed domains** 里添加 iMario 的 API 主机。Team 或 Enterprise 套餐要由管理员来添加。上传的图片会保存到你的 Library（资料库）。

问卷或访谈提纲不需要上传。把文档交给助手，让它直接运行就行：助手会把题目逐条录入，iMario 再存成问卷或提纲，放进你的资料库。题干和答案选项都会保留；跳题逻辑、矩阵题和题目里的图片不会带过来，助手应该把这一点告诉你。

只有大致轮廓的想法，可以用文字描述代替图片来测试。这时结果里会注明，受访者回应的是一段描述，而不是图片本身。

## 3. 验证连接（先不发起调研）
重新连接客户端，查看它列出的服务器和工具。服务器提供这些工具：`list_audiences`、`create_audience`、`get_audience`、`estimate_study`、`run_study`、`get_study`、`request_upload`（为自动上传做准备）和 `request_manual_upload`（手动上传的备用方案）。

对智能体说：“列出我能访问的 iMario 人群。不要创建人群，也不要运行调研。”然后确认返回的人群定义属于你要用的那个工作区。

接着，从这份列表里取一个人群 ID，让智能体做一次预估。批准运行之前，先核对费用、可用余额和预算限制，看清系统拒绝了哪些人群。连接成功，并不等于已经获准花积分做调研。

## 4. 运行并回到结果
决定运行后，智能体会调用 `run_study`，拿到 `run_id`、`study_id` 和 `web_url`。重试同一次提交时，沿用同一个幂等键。用 `get_study` 查询进度，避免高频轮询。

解读结果之前，先看 `outcome`。遇到 `partial_answers`，要以实际完成的数量为准；`no_answers` 不能解读成 0% 的结论。打开 `web_url` 可以查看这次调研。生成报告、只向选了某个选项的受访者追问，这两件事都要在网页端完成。

## 问题排查与撤销授权
| 现象 | 处理方法 |
|---|---|
| 找不到端点 | 检查服务器地址有没有拼错；如果是自托管部署，确认它开放了 `/mcp` |
| HTTP 401 | 重新授权连接（在 Claude Code 里是 `/mcp` > **Authenticate**），或者检查密钥对不对、有没有撤销、持有人还是不是工作区成员 |
| HTTP 429 | 降低这个密钥上所有调用的频率；轮询和各个工具共用同一个限额 |
| `audience_rejected` | 查看拒绝原因；不要悄悄换成别的人群 |
| `daily_budget_exceeded` | 缩小调研规模，或者等到 UTC 00:00，也可以请所有者或管理员在 Settings > MCP & API 里调高每日上限 |
| `insufficient_credits` | 查看工作区钱包；换新密钥不会增加积分 |
| 能列出工具，但没有技能 | 单独安装配套技能 |

要轮换 API 密钥，在 **Settings > MCP & API** 里点击 **Regenerate**，旧密钥从下一次请求起失效。要让某个应用再也访问不了工作区，就在 **Connected apps** 下点它旁边的垃圾桶图标；它的登录从下一次请求起失效，之后必须重新授权。这两种操作都不会取消已经提交的调研。在应用里删掉这个服务器，并不会在 iMario 这边断开连接。