连接 iMario 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 步里的命令，再装上配套技能；第 1a 步的授权，还是要你自己来。

1a. 授权连接（ChatGPT、Claude、Claude Code、Codex、VS Code）

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

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

把 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

claude mcp add --transport http imario YOUR_MCP_ENDPOINT

然后在 Claude Code 里运行 /mcp，选中 imario，再选择 Authenticate。浏览器会打开第 1a 步里的授权页面。配置作用域和移除方法，参见 Claude Code 的 MCP 说明。

Codex

codex mcp add imario --url YOUR_MCP_ENDPOINT
codex mcp login imario

第二条命令会在浏览器里打开授权页面。详见 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 也可以直接用密钥：

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

发送自己的图片和问卷

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

生成了上传链接，或者算出了调研价格，都不代表图片已经传到了。助手应该等 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 可以查看这次调研。生成报告、只向选了某个选项的受访者追问，这两件事都要在网页端完成。

问题排查与撤销授权

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