# 连接 AI 助手 (MCP)

<span data-t="appName">Your AI Connector</span> 提供了一个官方的 **MCP 服务器** —— 这是一个模型上下文协议（Model Context Protocol）端点，
让像 **Claude Code**、**Claude Desktop**、
**Cursor** 以及您自己的应用程序能够直接驱动您的 <span data-t="appName">Your AI Connector</span> 账户。用自然语言提问
（例如“列出我的 AI 智能体”、“添加此潜在客户”、“本周 AI 花费了多少？”），
助手就会为您调用 <span data-t="appName">Your AI Connector</span> API。

这与您通过 [API 密钥](api-access.md) 访问的 v1 API 相同，使用您自己的 API 密钥进行身份验证。MCP 服务器为我们已发布的 API 规范中的每个操作构建了一个工具，因此它涵盖了 v1 API 的大部分（但并非全部）功能：联系人、消息、营销活动、AI 代理、自定义函数、知识库、预约、分析、标签、列表、广播、交易、渠道连接和子账户。自动化功能目前可以通过 MCP 列出和读取，但尚无法创建或编辑；请在应用程序中进行这些操作。
在它所公开的功能范围内，没有针对每个工具的权限设置，也没有默认的只读限制，因此 API 密钥即是全部的访问控制。

- **端点：** `https://mcp.youraiconnector.com/mcp`
- **身份验证：** 您的 <span data-t="appName">Your AI Connector</span> API 密钥（作为 `X-API-Key` 标头发送）
- **要求：** 拥有 API 访问权限的套餐。[创建 API 密钥 →](api-access.md#generating-your-api-key)


> 您的 API 密钥作用于**您自己的账户**，具有与 API 其他部分相同的权限——如果您使用的是代理计划（见下文），它还可以读取您管理的客户账户。请像对待密码一样妥善保管它。您可以随时在“设置”→“集成”→“API 密钥”中撤销它，这将立即切断助手的访问权限。

## Claude Code



```bash
claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"
```

然后在 Claude Code 中运行 `/mcp` 以确认它显示 **ai-connector ✓ connected**。

默认情况下，服务器以 **local**（本地）范围添加（仅限您本人，仅限当前项目）。
使用 `--scope user` 使其在您的所有项目中可用，或使用 `--scope
project` to commit it to a repo's `.mcp.json` 供您的团队使用：

```json
{
  "mcpServers": {
    "ai-connector": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

## Claude Desktop

将该服务器添加为自定义连接器。它是在您的 Claude 账户中设置的，因此它既适用于 Claude Desktop，也适用于 claude.ai（免费的 Claude 账户可以添加一个自定义连接器）。

1. 打开 **Customize → Connectors**，点击 **+ Add**，然后选择 **Add custom connector**。
2. 为其命名并输入 `https://mcp.youraiconnector.com/mcp` 作为 URL。
3. 在 **Authentication** 下，选择 **No sign in**。MCP 服务器没有登录页面：选择登录选项会导致“无法注册到……登录服务”的错误。
4. 在 **Request headers** 下，添加一个名为 `X-API-Key` 的标头，并将您的 API 密钥作为其值。
5. 点击 **Add**。<span data-t="appName">Your AI Connector</span> 工具将出现在新对话的工具菜单中。

**没有 Request headers 字段？** 您的 Claude Desktop 版本过旧：请更新它，或者改用配置文件。配置文件（`claude_desktop_config.json`，Settings → Developer → Edit Config）仅在您的计算机上运行程序，并会忽略 `url` 条目，因此它需要小型的 `mcp-remote` 桥接程序，这需要 [Node.js](https://nodejs.org) 18 或更高版本：

```json
{
  "mcpServers": {
    "ai-connector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.youraiconnector.com/mcp",
        "--header",
        "X-API-Key:${AI_CONNECTOR_KEY}"
      ],
      "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" }
    }
  }
}
```

请保持 `X-API-Key:${AI_CONNECTOR_KEY}` 的书写格式完全一致，冒号后不要有空格（在 Windows 上，空格会拆分标头），并且仅将您的密钥放入 `env` 中。然后完全退出 Claude Desktop（在 Windows 上，右键点击托盘图标 → Quit），然后再重新打开。

## ChatGPT

ChatGPT 目前无法连接到该 MCP 服务器。其自定义连接器
表单仅提供 **OAuth** 或 **无身份验证** 选项，而 <span data-t="appName">Your AI Connector</span> MCP
服务器使用您的 API 密钥进行登录，该密钥作为请求头发送。选择 OAuth
会失败并提示“无法发现 OAuth 设置”，而选择“无身份验证”则会被拒绝，
因为每个请求都需要该密钥。

请改用允许设置请求头的助手：
[Claude Code](#claude-code)、[Claude Desktop](#claude-desktop)、
[Cursor 或其他 MCP 客户端](#cursor--other-mcp-clients)，或者
[Claude API](#the-claude-api-build-it-into-your-own-app)。

ChatGPT 仍然可以在不连接的情况下阅读帮助文档：请参阅
[帮助文档是内置的](#the-help-docs-are-built-in) 以获取公开的
`llms.txt` 文件。

## Cursor 及其他 MCP 客户端

大多数支持 MCP 的编辑器使用上述相同的 `.mcp.json` 格式（带有 `url` 和 `X-API-Key` 标头的 HTTP 服务器）。添加一个指向 `https://mcp.youraiconnector.com/mcp` 的 `ai-connector` 服务器，并在标头中粘贴您的 API 密钥。

## Claude API（构建到您自己的应用程序中）

您可以通过 Claude API 的 MCP 连接器以编程方式连接此 MCP 服务器，这样您构建的代理（Agent）无需单独的客户端即可使用 <span data-t="appName">Your AI Connector</span> 工具：
```json
{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my AI agents" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "ai-connector",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}
```

## 您可以做什么

在 MCP 服务器公开的 v1 API 部分中，助手会自动选择正确的工具：

- **AI 智能体：** 列出、创建、更新、暂停/恢复、检查配置。
- **联系人：** 搜索、创建、标记、添加到列表、导入。
- **知识库 / 常见问题解答：** 添加、编辑、批量导入、批准 AI 建议。
- **消息：** 阅读对话、向联系人发送消息。
- **预约：** 列出、预订、取消。
- **任务：** 创建、完成、列出。
- **分析：** 消息统计、额度使用情况、AI 成本。
- **渠道：** 检查连接状态、启动连接流程。
## 询问有关您客户账户的信息（代理商）

一个连接即可覆盖您管理的所有账户。您无需为每个客户添加第二个连接：在代理计划中，助手可以读取您名下的任何客户账户，因此您可以在一次对话中询问所有客户的相关信息。

只需说出客户名称即可：

- “Bella's Bistro 有多少个联系人？”
- “本周我每个客户的 AI 花费是多少？”
- “Northside Dental 的渠道状态如何，本周收到了多少次聊天？”
这涵盖了读取联系人、消息、聊天记录、营销活动、预约、任务、标签、事件、常见问题解答、知识库来源、电话号码、渠道、Webhook 和分析数据。在执行任何操作之前，我们会核实该账户确实属于您——如果请求的账户不存在，系统会返回“未找到”。如果不指定客户，助手将像往常一样读取您自己的账户。

**更改客户账户**的操作方式相同。API 中所有接受客户账户的操作都适用于指定客户：设置 AI 智能体、知识库、自定义函数、WhatsApp 模板、入口点、渠道连接、联系人、标签、广播、预约、交易和任务，以及发送消息。例外情况是代理商级别的操作，这些操作始终在您自己的代理商账户上运行：管理客户账户本身（限制、功能、定价、暂停）、快照、您的团队和 API 密钥。目前尚不支持为指定客户添加或从其列表中删除联系人；请使用该客户自己的密钥或在其账户中执行此操作。[代理商 API 指南](../agency/api-for-agencies.md#where-sub_account_id-is-supported)列出了支持的操作。
::: neutral-mcp
代理工具仅在标准的、无品牌的地址 `https://mcp.youraiconnector.com/mcp` 上提供。您自有域名的白标 MCP 地址 (`mcp.youragency.com`) 是为您的客户构建的，其中不包含这些工具，因此在管理客户账户时，请连接到标准的、无品牌的地址。
:::

对于**在同一个登录名下经营多家企业**的客户，这也是解决方案。为每家企业创建一个独立的账户，然后邀请该客户的电子邮件作为所有账户的团队成员：他们只需登录一次，即可通过侧边栏的账户选择器在不同品牌之间切换。

### 测试客户的智能体

要求助手尝试使用客户的智能体（例如：“向客户 X 的 Bakery 智能体发送‘你们周日送货吗？’并向我展示它的操作”）。它会使用您的代理密钥和客户的 `sub_account_id` 发送“试用”消息，等待并读取回复以及智能体执行的任何操作。无需智能体的副本。如果助手提示您不是代理账户，说明它连接的是客户的密钥：请使用您代理账户的密钥重新连接。请参阅 [试用](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant)。

## 具有工具数量限制的客户端

::: neutral-mcp
某些 AI 客户端仅接受工具数量有限的服务器。例如，Composio 会拒绝列出超过 500 个工具的服务器，并导致无法导入任何工具。完整的代理连接所列出的工具数量超过了此限制，因此请在地址中添加 `?tags=`，仅包含您需要的工具组。

对于想要列出其客户账户、读取其联系人、聊天记录和消息，以及发送消息的代理：

```
https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages
```

这将加载大约 80 个工具。在您的请求中指定客户名称，助手就会如上所述对该客户的账户执行操作。

- 使用逗号分隔组；大小写均可。
- 若要添加单个工具，请使用 `tools=` 列出其确切名称，例如 `?tags=Contacts&tools=list_or_get_subaccounts`。您将获得任一列表中的所有工具。
- 帮助文档工具始终包含在内。
- API 密钥仍需放在 `X-API-Key` 标头（或 `Authorization: Bearer YOUR_API_KEY`）中，切勿放在地址中。
:::

## 内置帮助文档

MCP 服务器会向助手提供你的 **账户** 信息和这份 **文档**。有三个工具可以实时读取帮助文档，因此助手可以查询某个功能的工作原理或最近的变更，而不是进行猜测：

- `docs_search`：查找回答问题的相关章节，并返回这些章节及页面链接。
- `docs_read`：完整读取一个页面或其中的一个章节。
- `docs_list`：按区域列出所有页面。

无需任何设置，且文档工具绝不会触及你的账户数据。询问“入口点是如何工作的？”或“自动化功能有什么新变化？”，助手会优先搜索文档。由于这些工具直接读取帮助网站本身，一旦功能指南发布，助手就能立即获知该功能。

未通过 MCP 连接的助手仍然可以读取文档：将其指向 `https://docs.youraiconnector.com/llms.txt`（包含每个帮助页面及其 Markdown 版本链接的索引）或 `https://docs.youraiconnector.com/llms-full.txt`（包含整个文档的单个 Markdown 文件）。两者均为公开，无需密钥，并会随文档的每次更改而重新构建。

## 查找或生成您的 API 密钥

此连接使用的 API 密钥位于 **Settings → Integrations → API Key**（设置 → 集成 → API 密钥）——这是一个独立的版块，与 Webhooks 分开。请参阅 [API Access](api-access.md#generating-your-api-key) 获取具体步骤。

## 故障排除

- **“Connection refused” 或 “not found”** — 地址末尾缺少 `/mcp`。请使用 `https://mcp.youraiconnector.com/mcp`，而不是 `https://mcp.youraiconnector.com`。
- **`Needs authentication` / 401** — 您的 API 密钥缺失或错误。请使用有效的 `X-API-Key` 重新添加服务器。
- **“Could not discover OAuth settings” (ChatGPT)** — ChatGPT 的自定义连接器仅支持 OAuth 或无身份验证，而 MCP 服务器使用 API 密钥，因此 ChatGPT 目前无法连接。请参阅 [ChatGPT](#chatgpt)。
- **“Couldn't register with … sign-in service” 或 “add an OAuth Client ID” (Claude Desktop)** — 自定义连接器在添加时选择了登录选项。没有 OAuth 客户端 ID 可供输入：请删除该连接器，并重新添加，选择 **Authentication → No sign in**，并将您的 API 密钥作为 `X-API-Key` 请求标头，如 [Claude Desktop](#claude-desktop) 中所述。
- **编辑配置文件后 Claude Desktop 不显示工具** — 配置文件会忽略 `"url"` 条目；请使用自定义连接器或 [Claude Desktop](#claude-desktop) 中的 `mcp-remote` 表单，并完全退出并重新打开应用程序。
- **工具返回 `403`** — 您的套餐或团队角色不允许该操作；MCP 服务器不强制执行任何额外限制，这与 API 的权限检查相同。
- **Tool not found** — 工具列表是根据 API 实时生成的，因此它始终与当前版本匹配；请重新连接以刷新。
- **关于您自己域名的安全或证书警告** — 仅将 DNS 记录指向我们是不够的：子域名在提供安全连接之前，还必须在仪表板中进行验证。白标代理商可以从 **Settings → White Labeling** 下的 **Custom domain** 卡片中将 MCP 地址放在自己的域名上（例如 `mcp.youragency.com`）——先在您的注册商处添加 CNAME，然后在 **MCP domain (AI assistants)** 模块中输入主机名并点击 **Verify**，流程与您的其他品牌子域名相同。品牌化地址不包含代理工具；请继续使用标准的非品牌化地址来使用这些工具。在您的品牌化地址验证通过之前，请使用标准的非品牌化地址：它与客户共享是安全的。

---

## 后续步骤

- [API Access](api-access.md) ——生成或轮换此连接使用的密钥。
- [Webhooks](webhooks.md) ——此基于拉取的 MCP 连接的基于推送的对应功能。