---
title: "客户端设置"
description: "在 ChatGPT、Claude Desktop、Cursor 及其他客户端中配置 Minds MCP。"
canonical_url: "https://getminds.ai/mcp/zh/setup"
last_updated: "2026-08-13T13:01:21.576Z"
---

# 客户端设置

本指南会把 [Minds MCP 市场调研服务器](/mcp/overview) 连接到支持远程工具的 AI 客户端。服务器 URL 使用 `https://getminds.ai/mcp`。

## ChatGPT

1. 进入 **ChatGPT** → **Settings** → **Connected Apps**
2. 搜索 "Minds" 或添加 MCP URL:`https://getminds.ai/mcp`
3. 点击 **Connect** 并通过 OAuth 授权(登录你的 Minds 账户)
4. 开始对话 —— 让 ChatGPT 创建 Mind、运行 panel 并分析结果

ChatGPT 会在对话中内联渲染交互式 widget —— 带分组回复、柱状图和可点击 Mind 头像的 panel 结果直接在聊天中显示。

## Claude Desktop

### 方式 A:远程 Connector(推荐 —— 支持交互式 widget)

1. 打开 Claude Desktop → **Customize** → **Connectors**(或 **Settings** → **Connections**)
2. 将 `https://getminds.ai/mcp` 添加为新的远程 connector
3. 出现提示时通过 OAuth 授权 —— 登录你的 Minds 账户
4. 授权后 tool 会自动出现

### 方式 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 支持

公布的 15 个工具会返回结构化文本和可点击链接。服务器还为显式集成注册了另外 18 个规范生命周期工具。Widget 展示取决于客户端及其版本，因此集成必须在只有结构化结果和文本结果时也能完整使用。

## Claude Code (CLI)

```bash
claude mcp add --transport http mindsai https://getminds.ai/mcp \
  --header "Authorization: Bearer minds_YOUR_API_KEY"
```

## Cursor

1. 打开 Cursor Settings → **MCP**
2. 添加新的 server,URL:`https://getminds.ai/mcp`
3. 出现提示时授权访问

## VS Code (GitHub Copilot)

1. 打开 VS Code Settings → **Extensions** → **GitHub Copilot** → **MCP Servers**
2. 将 `https://getminds.ai/mcp` 添加为新的 server
3. 出现提示时授权

## OpenRouter、Open WebUI 与 OpenAI 兼容网关

当 **模型提供方**（而不是客户端宿主）在服务器端执行 MCP 调用时——例如通过 OpenRouter 使用 `openai/*` 模型、直接调用 OpenAI Responses API、或 Open WebUI 以 *Native function-calling* 模式运行——你 **必须使用 API key 身份验证**。OAuth 在这条路径上不生效。

### 为什么这里 OAuth 不行

当 Open WebUI 以 Native 模式运行 `openai/gpt-5.2` agent 时，它会在请求中将 MCP 工具描述符一起传递给 OpenAI/OpenRouter。OpenAI 服务器端的 MCP runner（运行在 Azure 上，可通过 `User-Agent: python-httpx/*` 识别）随后直接调用我们的 `/mcp` endpoint。该 runner 只会携带在工具注册时配置的**静态 header**——**不会**执行 MCP OAuth 握手（RFC 9728 / 8414 / 7591）。因此 Open WebUI 的 *OAuth — 转发系统用户的 access token* 模式在这里是无效的：用户的 token 从未离开 Open WebUI。

结果：Minds 收到的请求没有 `Authorization` header，返回：

```text
401 Unauthorized
www-authenticate: Bearer resource_metadata="https://getminds.ai/.well-known/oauth-protected-resource"
{"error":{"code":-32001,"message":"Authentication required. Connect your Minds account via OAuth or provide an API key."}}
```

### Open WebUI 设置

1. 在 [Settings → API Keys](/settings/api-keys) 生成一个 API key（格式 `minds_…`）。
2. 在 Open WebUI 中：**Admin → 设置 → 工具 → + 连接**。
3. 设置：

  - **类型**：`Streamable HTTP (MCP)`
  - **URL**：`https://getminds.ai/mcp`
  - **身份验证**：`Bearer`（不是 OAuth）
  - **Token**：你的 `minds_…` key
4. 保存连接。
5. 在 agent 的*工具*选项卡中，激活 **Get Minds** 工具。
6. 让 agent 列出你的 Minds 来测试。

如果你保留 `身份验证：OAuth`，只有在 Open WebUI 自己执行工具时（即 *Function calling = Default*，而非 *Native*）调用才会成功。大多数用户需要 Native 模式，所以请使用 Bearer key。

### 直接调用 OpenRouter（编程方式）

在调用 OpenRouter chat completions API 并附带 Minds MCP server 时，在工具描述符的静态 `headers` 字段中传入 API key：

```json
{
  "type": "mcp",
  "server_label": "minds",
  "server_url": "https://getminds.ai/mcp",
  "headers": {
    "Authorization": "Bearer minds_YOUR_API_KEY"
  }
}
```

直接使用 OpenAI Responses API 同理：

```python
from openai import OpenAI
client = OpenAI()
client.responses.create(
    model="gpt-5.2",
    input="列出我的 Minds",
    tools=[{
        "type": "mcp",
        "server_label": "minds",
        "server_url": "https://getminds.ai/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['MINDS_API_KEY']}"},
    }],
)
```

## API Key 身份验证

用于编程访问或不支持 OAuth 的客户端:

1. 在 Minds 中进入 [Settings → API Keys](/settings/api-keys)
2. 创建一个新的 API key(以 `minds_` 开头)
3. 以 Bearer token 方式传入:`Authorization: Bearer minds_your_key_here`

## OAuth Discovery

对于构建 MCP 集成的开发者,OAuth metadata 可在以下 endpoint 获取:

<table>
<thead>
  <tr>
    <th>
      Endpoint
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        /.well-known/oauth-protected-resource
      </code>
    </td>
    
    <td>
      Protected resource metadata (RFC 9728)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /.well-known/oauth-authorization-server
      </code>
    </td>
    
    <td>
      Authorization server metadata (RFC 8414)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /oauth/register
      </code>
    </td>
    
    <td>
      Dynamic Client Registration (RFC 7591)
    </td>
  </tr>
</tbody>
</table>

要求使用 OAuth 2.1 + PKCE (S256)。支持 public client(`token_endpoint_auth_method: "none"`)。

## 故障排查

### "Authentication required" 错误

请确认已完成 OAuth 授权流程。断开并重新连接你的 MCP 客户端以重新授权。

如果你是通过 **OpenRouter、Native 模式的 Open WebUI 或直接调用 OpenAI Responses API** 调用 Minds，则此路径不支持 OAuth——模型提供方服务器端的 MCP runner 无法执行 OAuth 握手。请将 MCP 连接切换为使用 `minds_…` key 的 **Bearer / API key 身份验证**。参见上面的 [OpenRouter、Open WebUI 与 OpenAI 兼容网关](#openrouteropen-webui-%E4%B8%8E-openai-%E5%85%BC%E5%AE%B9%E7%BD%91%E5%85%B3)。

### Claude Desktop OAuth 无法完成

若 OAuth 弹窗打开但始终未完成,改用 API key 方式(上面的方式 B)。Claude Desktop 的远程 connector OAuth 有时不稳定。

### Mind not found

使用 `sparkName` 时,请确保名称与你的 Mind 高度匹配。系统使用模糊匹配,但要求达到合理的相似度分数。

### Mind 仍在训练

新创建的 Mind 可能需要一些时间完成训练。开始对话前先用 `get_mind_status` 检查训练是否完成。

### Panel 问题超时

包含较多分组的 panel 问题可能耗时超过 2 分钟。尝试减少分组数量或简化问题。

### PDF 导出未就绪

PDF 报告是异步生成的。使用 `get_panel_status` 检查导出状态。生成通常需要 30-60 秒。