--- title: "客户端设置" description: "在 ChatGPT、Claude、Claude Code、Codex、Gemini CLI、Cursor、VS Code、Windsurf、OpenRouter 和 Open WebUI 中配置 Minds MCP，并使用 API key 身份验证。" canonical_url: "https://getminds.ai/mcp/zh/setup" last_updated: "2026-10-01T16:06:49.945Z" --- # 客户端设置 下方每个客户端看到的都是相同的 个公布工具，数量读取自实时服务器。请以所连接服务器的 `tools/list` 响应为准。 本指南会把 [Minds MCP 市场调研服务器](/mcp/overview) 连接到支持远程工具的 AI 客户端。服务器 URL 使用 `https://getminds.ai/mcp`。 ## ChatGPT 请使用网页版 ChatGPT。可用性和权限取决于账户与工作区，请参阅 [OpenAI 当前的 MCP 设置指南](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)。 1. 打开 **Plugins**，选择 **Add → Create MCP App**。如果没有该选项，请开启开发者模式，或请工作区管理员允许自定义 MCP 应用。 2. 将名称设为 `Minds`，在 **Server URL** 中输入 `https://getminds.ai/mcp`，**Authentication** 选择 **OAuth**，确认风险提示后点击 **Create**。 3. 点击 **Continue to Minds**，登录你的 Minds 账户并选择 **Allow**。 4. 在新对话中输入 `@Minds`，请它列出你的 Audiences。范围较广的 Studies 必须先审阅并明确确认，才能执行。 如果你的账户在插件目录中能看到 Minds，也可以从 **Plugins** 添加，并以同样方式登录。 在 ChatGPT 桌面应用中，打开 **Plugins** 并选择 **Add → Add MCP server**。将类型设为 **Streamable HTTP**，URL 设为 `https://getminds.ai/mcp`，点击 **Save**，再点击 **Restart**，然后选择 **Authenticate** 登录 Minds。 [ChatGPT 设置指南](/guide/integration-chatgpt) 逐一展示每个界面，包括插件目录和桌面应用方式。 兼容的网页宿主可在对话内显示结果。移动端显示的 Minds 组件会提供前往 Minds 的链接，而非交互控件。 ## Claude（claude.ai 和 Claude Desktop） ### 远程连接器（组件支持取决于客户端） 自定义连接器在 claude.ai 和 Claude Desktop 中的用法相同，并会在两者之间同步。 1. 打开 **Customize** → **Connectors**，点击 **+**，然后选择 **Add custom connector** 2. 输入 `https://getminds.ai/mcp` 作为远程 MCP 服务器 URL，然后点击 **Add** 3. 点击 **Connect**，登录你的 Minds 账户，然后选择 **Allow** 4. 在对话中通过 **+** → **Connectors** 启用 Minds 在 Team 和 Enterprise 计划中，需由所有者先在 **Organization settings** → **Connectors** 下添加该连接器；成员随后在 **Customize** → **Connectors** 下连接自己的 Minds 账户。 ### 方式 B:本地 Connector(API key,仅文本) 添加到你的配置文件(macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "mindsai": { "command": "npx", "args": [ "-y", "mcp-remote", "https://getminds.ai/mcp", "--header", "Authorization: Bearer minds_YOUR_API_KEY" ] } } } ``` 重启 Claude Desktop。Tool 会立即可用,但本地 connector 无法使用交互式 widget。 ### Claude 中的 Widget 支持 公布的工具会返回文本回答和可点击链接，用于在 Minds webapp 中打开结果。服务器还为显式集成保留了更多可调用的规范生命周期工具；参见[工具参考](/mcp/tools)。交互式 widget 的表现取决于客户端及其版本，因此集成不能假定 widget 已渲染，必须在只有结构化结果和文本结果时也能完整使用。 ## Claude Code (CLI) ```bash claude mcp add --transport http minds https://getminds.ai/mcp ``` 在 Claude Code 中运行 `/mcp`，选择 `minds`，然后选择 **Authenticate**，即可通过 OAuth 登录。API 密钥是可选的：如需改用 API 密钥，请在命令中添加 `--header "Authorization: Bearer minds_YOUR_API_KEY"`。 ## Codex 使用 Codex CLI： ```bash codex mcp add minds --url https://getminds.ai/mcp codex mcp login minds ``` `codex mcp login` 会打开 Minds 登录页面。Codex 通过 Client ID Metadata Document 注册自身，因此你无需提供 client ID 或 secret。 在 Codex 应用或 IDE 扩展中，打开 **Settings → MCP servers**，选择 **Add server**，选取 **Streamable HTTP**，然后输入 `https://getminds.ai/mcp`。保存并重启后，选择 **Authenticate**。 如需改用 API 密钥，请在 `~/.codex/config.toml` 的 `[mcp_servers.minds]` 下设置 `bearer_token_env_var = "MINDS_API_KEY"`，并在该环境变量中导出密钥。 ## Gemini CLI 将服务器添加到 `~/.gemini/settings.json`： ```json { "mcpServers": { "minds": { "httpUrl": "https://getminds.ai/mcp" } } } ``` 也可以运行 `gemini mcp add --transport http minds https://getminds.ai/mcp`。Gemini CLI 会从服务器发现 OAuth，并在首次使用时打开登录页面。也可以运行 `/mcp auth minds`。 ## Cursor 1. 将服务器添加到 `~/.cursor/mcp.json`，或添加到项目中的 `.cursor/mcp.json`： ```json { "mcpServers": { "minds": { "url": "https://getminds.ai/mcp" } } } ``` 1. 在 Cursor 提示时进行身份验证，并登录 Minds。 ## VS Code (GitHub Copilot) 1. 在命令面板中运行 **MCP: Add Server**，选择 **HTTP**，然后输入 `https://getminds.ai/mcp`。也可以将其添加到 `.vscode/mcp.json`： ```json { "servers": { "minds": { "type": "http", "url": "https://getminds.ai/mcp" } } } ``` 1. 启动服务器，并在提示时允许 VS Code 登录 Minds。随后，Minds 工具会出现在 Copilot Chat 的 agent 模式中。 ## Windsurf 在 Cascade 面板中打开 **…** 菜单，选择 **Open MCP config file**。在 `mcpServers` 下添加 Minds： ```json { "mcpServers": { "minds": { "serverUrl": "https://getminds.ai/mcp" } } } ``` 保存文件，然后在 Windsurf 提示时登录 Minds。如需改用 API 密钥，请在该条目中添加 `"headers": { "Authorization": "Bearer ${env:MINDS_API_KEY}" }`。 ## OpenRouter、Open WebUI 与 OpenAI 兼容网关 认证取决于哪个客户端执行 MCP 请求，以及它转发什么凭据。模型提供商的 API 密钥不能用于 Minds 认证。 ### 转发 OAuth 令牌 OpenAI Responses API 接受通过 MCP 工具的 `authorization` 字段传入现有 OAuth 访问令牌。应用需单独处理授权和刷新，并在每次请求中提供令牌。参见 [OpenAI MCP 认证指南](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)。 ### Open WebUI / OpenRouter 配置指向 `https://getminds.ai/mcp` 的 Streamable HTTP 连接。若所选客户端或执行模式无法完成 OAuth 并转发令牌，请在[设置 → API 密钥](/settings/api-keys)创建 Minds 密钥，并通过客户端的安全存储配置 Bearer 认证。用 `list_audiences` 测试。对于 OpenRouter 等网关，请检查当前 MCP 支持和描述符格式；兼容 OpenAI Chat Completions 本身不保证支持远程 MCP。 ### OpenAI Responses API 示例 本例从环境变量读取 Minds API 密钥。使用 OAuth 时，请先由应用取得有效的 Minds 令牌，再将 `headers` 替换为 `"authorization": os.environ["MINDS_OAUTH_ACCESS_TOKEN"]`。 ```python import os from openai import OpenAI client = OpenAI() response = client.responses.create( model="gpt-5.2", input="List my Audiences", tools=[{ "type": "mcp", "server_label": "minds", "server_url": "https://getminds.ai/mcp", "headers": {"Authorization": f"Bearer {os.environ['MINDS_API_KEY']}"}, "allowed_tools": ["list_audiences"], "require_approval": "never", }], ) print(response.output_text) ``` ## API Key 身份验证 用于编程访问或不支持 OAuth 的客户端: 1. 在 Minds 中进入 [Settings → API Keys](/settings/api-keys) 2. 创建一个新的 API key(以 `minds_` 开头) 3. 以 Bearer token 方式传入:`Authorization: Bearer minds_your_key_here` ## Scopes OAuth 客户端会请求 OpenID 基础权限（`openid`、`email`、`profile`）以及下列 Minds 权限范围。在你选择 **Allow** 之前，Minds 授权同意页面会用产品术语说明每个权限范围。未请求任何权限范围的客户端将获得全部权限范围。 ## OAuth Discovery 对于构建 MCP 集成的开发者,OAuth metadata 可在以下 endpoint 获取:
Endpoint 说明
/.well-known/oauth-protected-resource Protected resource metadata (RFC 9728)
/.well-known/oauth-authorization-server Authorization server metadata (RFC 8414)
/oauth/register Dynamic Client Registration (RFC 7591)
要求使用 OAuth 2.1 + PKCE (S256)。支持 public client(`token_endpoint_auth_method: "none"`)。 原生客户端可以注册 loopback 重定向 URI（`http://127.0.0.1`、`http://localhost`、`http://[::1]`）；端口不参与匹配，因此客户端可以监听任意空闲端口（RFC 8252）。客户端也可以使用 Client ID Metadata Document：以发布其元数据的 https URL 作为 `client_id`（`client_id_metadata_document_supported: true`）。令牌端点接受请求正文中的 `client_id`，或使用空密钥的 HTTP Basic 认证。 ## 故障排查 ### "Authentication required" 错误 请确认已完成 OAuth 授权流程。断开并重新连接你的 MCP 客户端以重新授权。 确认执行 MCP 的组件转发有效的 Minds Bearer 凭据。重新连接 OAuth 或通过管理该令牌的客户端刷新它；无法转发 OAuth 令牌时使用 API 密钥。提供商密钥或主机登录不能替代 Minds 凭据。 ### 对你在 Minds 中可以打开的 Study、Audience 或 Mind 显示 "Not authorized" MCP 客户端登录的 Minds 账户与该项目的所有者账户不同；错误信息会注明已连接的账户。请使用所有者账户重新连接客户端，或将该项目共享给已连接的账户。 ### Claude Desktop OAuth 无法完成 若 OAuth 弹窗打开但始终未完成,改用 API key 方式(上面的方式 B)。Claude Desktop 的远程 connector OAuth 有时不稳定。 ### Mind not found 使用 `mindName` 时,请确保名称与你的 Mind 高度匹配。系统使用模糊匹配,但要求达到合理的相似度分数。 ### Mind 仍在训练 新创建的 Mind 可能需要一些时间完成训练。开始对话前先用 `get_mind_status` 检查训练是否完成。 ### Study 问题超时 包含较多分组的 study 问题可能耗时超过 2 分钟。尝试减少分组数量或简化问题。 ### PDF 导出未就绪 导出异步运行。使用相同的 `studyId` 和 `export_study` 返回的准确 `exportKind`、`exportFormat`、`exportJobId` 轮询 `get_study_status`。检查任务状态和下载地址；生成时间因情况而异。轮询超时不表示可以重复提交导出。 ### 结果一直加载或显示不完整 结果组件接收宿主更新，并在宿主允许时进行有次数限制的自动状态轮询。这不保证持续逐 token 流式输出。否则，请使用显示的刷新控件、让助手查询现有 Study，或打开返回的 Minds 链接。 直接问题使用 `get_study_status`，已确认计划使用 `get_study_run`。保留同一 `studyId`；加载或超时不是重新提交的理由。应说明部分回答和不完整的回答覆盖情况。问题已结束并不能证明每个 Mind 都已回答。 ## n8n 工作流 使用 [Minds n8n 社区节点](/guide/integration-n8n) 来创建 Study、预览研究计划、检索 Study 和已保存的摘要，或将操作公开给 AI Agent。在自托管 n8n 上安装 `n8n-nodes-minds` 并连接 Minds API 密钥。该包已发布在 npm 上；n8n 验证正在审核中，因此尚无法在 n8n Cloud 上使用。请在 Minds 中单独审核并开始研究。