# Kết nối các Trợ lý AI (MCP)
Your AI Connector cung cấp một **MCP server** chính thức — một điểm cuối Model Context Protocol cho phép các trợ lý AI như **Claude Code**, **Claude Desktop**, **Cursor** và các ứng dụng của riêng bạn điều khiển trực tiếp tài khoản Your AI Connector của bạn. Hãy hỏi bằng ngôn ngữ tự nhiên ("liệt kê các tác nhân AI của tôi", "thêm khách hàng tiềm năng này", "tuần này tôi tốn bao nhiêu chi phí cho AI?") và trợ lý sẽ gọi API Your AI Connector thay cho bạn.
Đây là cùng một API v1 mà bạn truy cập bằng [API key](api-access.md), được xác thực bằng chính API key của bạn. Máy chủ MCP xây dựng một công cụ cho mỗi thao tác trong đặc tả API đã công bố của chúng tôi, vì vậy nó bao gồm hầu hết, nhưng không phải tất cả, API v1: danh bạ, tin nhắn, chiến dịch, tác nhân AI, hàm tùy chỉnh, cơ sở kiến thức, cuộc hẹn, phân tích, thẻ, danh sách, chương trình phát sóng, giao dịch, kết nối kênh và tài khoản phụ. Các tự động hóa có thể được liệt kê và đọc, nhưng chưa thể tạo hoặc chỉnh sửa thông qua MCP; hãy xây dựng chúng trong ứng dụng.
Trong phạm vi những gì nó hiển thị, không có quyền cho từng công cụ và không có mặc định chỉ đọc, vì vậy API key chính là toàn bộ quyền kiểm soát truy cập.
- **Điểm cuối (Endpoint):** `https://mcp.youraiconnector.com/mcp`
- **Xác thực:** khóa API Your AI Connector của bạn (được gửi dưới dạng tiêu đề `X-API-Key`)
- **Yêu cầu:** gói có quyền truy cập API. [Tạo khóa API →](api-access.md#generating-your-api-key)
> Khóa API của bạn hoạt động trên **tài khoản của chính bạn**, với các quyền tương tự như phần còn lại của API — và có thể đọc các tài khoản khách hàng mà bạn quản lý, nếu bạn đang sử dụng gói đại lý (xem bên dưới). Hãy coi nó như mật khẩu. Bạn có thể thu hồi nó bất kỳ lúc nào từ Cài đặt → Tích hợp → Khóa API, thao tác này sẽ ngay lập tức cắt quyền truy cập của trợ lý.
## Claude Code
```bash
claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
--header "X-API-Key: YOUR_API_KEY"
```
Sau đó chạy `/mcp` bên trong Claude Code để xác nhận rằng nó hiển thị **ai-connector ✓ connected**.
Theo mặc định, máy chủ được thêm ở phạm vi **cục bộ** (chỉ bạn, dự án này).
Sử dụng `--scope user` để làm cho nó khả dụng trong tất cả các dự án của bạn, hoặc `--scope
project` to commit it to a repo's `.mcp.json` cho nhóm của bạn:
```json
{
"mcpServers": {
"ai-connector": {
"type": "http",
"url": "https://mcp.youraiconnector.com/mcp",
"headers": { "X-API-Key": "YOUR_API_KEY" }
}
}
}
```
## Claude Desktop
Thêm máy chủ dưới dạng trình kết nối tùy chỉnh. Nó được thiết lập trong tài khoản Claude của bạn, vì vậy nó hoạt động trên cả Claude Desktop và claude.ai (các tài khoản Claude miễn phí có thể thêm một trình kết nối tùy chỉnh).
1. Mở **Customize → Connectors**, nhấp vào **+ Add**, sau đó chọn **Add custom connector**.
2. Đặt tên cho nó và nhập `https://mcp.youraiconnector.com/mcp` làm URL.
3. Trong phần **Authentication**, chọn **No sign in**. Máy chủ MCP không có trang đăng nhập: việc chọn một tùy chọn đăng nhập sẽ dẫn đến lỗi "Couldn't register with … sign-in service".
4. Trong phần **Request headers**, thêm một tiêu đề có tên là `X-API-Key` với khóa API của bạn làm giá trị.
5. Nhấp vào **Add**. Các công cụ Your AI Connector sẽ xuất hiện trong menu công cụ của một cuộc trò chuyện mới.
**Không thấy trường Request headers?** Phiên bản Claude Desktop của bạn đã cũ: hãy cập nhật nó hoặc sử dụng tệp cấu hình thay thế. Tệp cấu hình (`claude_desktop_config.json`, Settings → Developer → Edit Config) chỉ chạy các chương trình trên máy tính của bạn và bỏ qua mục `url`, vì vậy nó cần cầu nối `mcp-remote` nhỏ, yêu cầu [Node.js](https://nodejs.org) phiên bản 18 trở lên:
```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" }
}
}
}
```
Giữ nguyên `X-API-Key:${AI_CONNECTOR_KEY}` chính xác như đã viết, không có khoảng trắng sau dấu hai chấm (trên Windows, khoảng trắng sẽ làm tách tiêu đề) và chỉ đặt khóa của bạn vào `env`. Sau đó, thoát hoàn toàn Claude Desktop (trên Windows, nhấp chuột phải vào biểu tượng trên khay hệ thống → Quit) và mở lại.
## ChatGPT
ChatGPT hiện không thể kết nối với MCP server. Biểu mẫu kết nối tùy chỉnh của nó chỉ cung cấp **OAuth** hoặc **Không xác thực**, trong khi MCP server Your AI Connector đăng nhập bằng khóa API của bạn, được gửi dưới dạng tiêu đề yêu cầu. Việc chọn OAuth sẽ thất bại với thông báo "không thể khám phá cài đặt OAuth", và Không xác thực sẽ bị từ chối vì mọi yêu cầu đều cần khóa.
Hãy sử dụng một trợ lý cho phép bạn đặt tiêu đề yêu cầu thay thế:
[Claude Code](#claude-code), [Claude Desktop](#claude-desktop),
[Cursor hoặc một ứng dụng khách MCP khác](#cursor--other-mcp-clients), hoặc
[Claude API](#the-claude-api-build-it-into-your-own-app).
ChatGPT vẫn có thể đọc tài liệu trợ giúp mà không cần kết nối: xem
[Tài liệu trợ giúp được tích hợp sẵn](#the-help-docs-are-built-in) cho các tệp `llms.txt` công khai.
## Cursor & các ứng dụng khách MCP khác
Hầu hết các trình chỉnh sửa hỗ trợ MCP đều sử dụng cùng một cấu trúc `.mcp.json` như hiển thị ở trên (một máy chủ HTTP với `url` và tiêu đề `X-API-Key`). Thêm máy chủ `ai-connector` trỏ đến `https://mcp.youraiconnector.com/mcp` và dán khóa API của bạn vào tiêu đề.
## Claude API (tích hợp vào ứng dụng của riêng bạn)
Bạn có thể kết nối MCP server theo chương trình với trình kết nối MCP của Claude API, vì vậy một tác nhân (agent) mà bạn xây dựng có thể sử dụng các công cụ Your AI Connector mà không cần ứng dụng khách riêng biệt:
```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"
}
]
}
```
## Bạn có thể làm gì
Trong phần API v1 mà máy chủ MCP hiển thị, trợ lý sẽ tự động chọn công cụ phù hợp:
- **Các tác nhân AI:** liệt kê, tạo, cập nhật, tạm dừng/tiếp tục, kiểm tra cấu hình.
- **Danh bạ:** tìm kiếm, tạo, gắn thẻ, thêm vào danh sách, nhập dữ liệu.
- **Cơ sở kiến thức / Câu hỏi thường gặp:** thêm, chỉnh sửa, nhập hàng loạt, phê duyệt các đề xuất của AI.
- **Tin nhắn:** đọc các cuộc hội thoại, gửi tin nhắn cho một liên hệ.
- **Cuộc hẹn:** liệt kê, đặt lịch, hủy lịch.
- **Tác vụ:** tạo, hoàn thành, liệt kê.
- **Phân tích:** thống kê tin nhắn, mức sử dụng tín dụng, chi phí AI.
- **Kênh:** kiểm tra trạng thái kết nối, bắt đầu luồng kết nối.
## Hỏi về tài khoản của khách hàng (đại lý)
Một kết nối bao gồm mọi tài khoản bạn quản lý. Bạn không cần thêm kết nối thứ hai cho mỗi khách hàng: trên gói đại lý, trợ lý có thể đọc bất kỳ tài khoản khách hàng nào dưới quyền của bạn, vì vậy bạn có thể hỏi về tất cả chúng trong một cuộc trò chuyện.
Chỉ cần nêu tên khách hàng:
- "Bella's Bistro có bao nhiêu liên hệ?"
- "AI đã tiêu tốn của mỗi khách hàng của tôi bao nhiêu trong tuần này?"
- "Trạng thái các kênh của Northside Dental như thế nào và có bao nhiêu cuộc trò chuyện đã diễn ra trong tuần này?"
Điều này bao gồm việc đọc danh bạ, tin nhắn, cuộc trò chuyện, chiến dịch, cuộc hẹn, tác vụ, thẻ, sự kiện, câu hỏi thường gặp, nguồn cơ sở kiến thức, số điện thoại, kênh, webhook và phân tích. Chúng tôi kiểm tra xem tài khoản có thực sự là của bạn trước khi thực hiện bất kỳ thao tác nào — việc yêu cầu một tài khoản không thuộc quyền sở hữu của bạn sẽ trả về kết quả "không tìm thấy". Nếu không nêu tên khách hàng, trợ lý sẽ đọc tài khoản của chính bạn, giống như trước đây.
**Việc thay đổi tài khoản của khách hàng** cũng hoạt động theo cách tương tự. Mọi hành động chấp nhận tài khoản khách hàng trong API đều khả dụng cho một khách hàng được chỉ định: thiết lập các tác nhân AI, cơ sở tri thức, các hàm tùy chỉnh, mẫu WhatsApp, điểm truy cập, kết nối kênh, danh bạ, thẻ, chương trình phát sóng, cuộc hẹn, giao dịch và tác vụ, cũng như gửi tin nhắn. Các ngoại lệ là những hành động ở cấp đại lý, vốn luôn chạy trên tài khoản đại lý của riêng bạn: quản lý chính các tài khoản khách hàng (giới hạn, tính năng, giá cả, tạm dừng), bản chụp nhanh (snapshots), nhóm của bạn và các khóa API. Việc thêm hoặc xóa danh bạ khỏi danh sách của khách hàng hiện chưa khả dụng cho khách hàng được chỉ định; hãy thực hiện việc đó từ khóa riêng của khách hàng đó hoặc trong tài khoản của họ. [Hướng dẫn API đại lý](../agency/api-for-agencies.md#where-sub_account_id-is-supported) liệt kê những gì được hỗ trợ.
::: neutral-mcp
Các công cụ đại lý chỉ có trên địa chỉ tiêu chuẩn, không gắn thương hiệu, `https://mcp.youraiconnector.com/mcp`. Địa chỉ MCP nhãn trắng (white-label) trên tên miền riêng của bạn (`mcp.youragency.com`) được xây dựng dành cho khách hàng của bạn và không bao gồm các công cụ này, vì vậy hãy kết nối bằng địa chỉ tiêu chuẩn, không gắn thương hiệu khi bạn quản lý tài khoản khách hàng.
:::
Đây cũng là câu trả lời cho khách hàng điều hành **nhiều doanh nghiệp dưới một thông tin đăng nhập**. Hãy cấp cho mỗi doanh nghiệp một tài khoản riêng, sau đó mời email của khách hàng làm thành viên nhóm trên tất cả các tài khoản đó: họ chỉ cần đăng nhập một lần và chuyển đổi giữa các thương hiệu của mình bằng bộ chọn tài khoản trong thanh bên.
### Kiểm thử tác nhân của khách hàng
Yêu cầu trợ lý dùng thử tác nhân của khách hàng ("gửi 'bạn có giao hàng vào Chủ Nhật không?' tới tác nhân Bakery của khách hàng X và cho tôi xem nó đã làm gì"). Trợ lý sẽ gửi tin nhắn Thử nghiệm (Try Out) cùng với khóa đại lý của bạn và `sub_account_id` của khách hàng, chờ đợi, sau đó đọc lại phản hồi cùng với bất kỳ hành động nào mà tác nhân đã thực hiện. Không cần bản sao của tác nhân. Nếu trợ lý thông báo rằng bạn không phải là tài khoản đại lý, nghĩa là nó đang được kết nối bằng khóa của khách hàng: hãy kết nối lại bằng khóa tài khoản đại lý của bạn. Xem [Thử nghiệm](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant).
## Các client có giới hạn công cụ
::: neutral-mcp
Một số AI client chỉ chấp nhận server với số lượng công cụ giới hạn. Ví dụ, Composio sẽ từ chối server liệt kê hơn 500 công cụ và không nhập bất kỳ công cụ nào trong số đó. Kết nối agency đầy đủ liệt kê nhiều hơn con số này, vì vậy hãy thêm `?tags=` vào địa chỉ với chỉ các nhóm công cụ bạn cần.
Đối với một agency muốn liệt kê các tài khoản khách hàng của mình, đọc danh bạ, cuộc trò chuyện và tin nhắn của họ, cũng như gửi tin nhắn:
```
https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages
```
Thao tác đó sẽ tải khoảng 80 công cụ. Hãy đặt tên khách hàng trong yêu cầu của bạn và trợ lý sẽ thực hiện trên tài khoản của khách hàng đó, như đã mô tả ở trên.
- Phân tách các nhóm bằng dấu phẩy; viết hoa hay viết thường đều được.
- Để thêm các công cụ đơn lẻ, hãy liệt kê tên chính xác của chúng bằng `tools=`, ví dụ `?tags=Contacts&tools=list_or_get_subaccounts`. Bạn sẽ nhận được mọi công cụ từ cả hai danh sách.
- Các công cụ trong tài liệu trợ giúp luôn được bao gồm.
- Khóa API vẫn được đặt trong tiêu đề `X-API-Key` (hoặc `Authorization: Bearer YOUR_API_KEY`), không bao giờ đặt trong địa chỉ.
:::
## Tài liệu trợ giúp được tích hợp sẵn
Máy chủ MCP cung cấp cho trợ lý **tài khoản** của bạn và **tài liệu** này. Ba công cụ đọc tài liệu trợ giúp trực tiếp, vì vậy trợ lý có thể tra cứu cách một tính năng hoạt động hoặc những gì đã thay đổi gần đây thay vì phải đoán:
- `docs_search`: tìm các phần trả lời cho một câu hỏi và trả về chúng cùng với liên kết trang.
- `docs_read`: đọc toàn bộ một trang hoặc một phần của trang đó.
- `docs_list`: liệt kê mọi trang theo khu vực.
Không cần thiết lập gì cả và các công cụ tài liệu không bao giờ chạm vào dữ liệu tài khoản của bạn. Hãy hỏi "entry points hoạt động như thế nào?" hoặc "có gì mới trong phần tự động hóa?" và trợ lý sẽ tìm kiếm tài liệu trước. Vì các công cụ đọc chính trang trợ giúp, một tính năng sẽ được trợ lý của bạn biết ngay khi hướng dẫn của nó được xuất bản.
Một trợ lý không được kết nối thông qua MCP vẫn có thể đọc tài liệu: hãy hướng nó đến `https://docs.youraiconnector.com/llms.txt` (chỉ mục của mọi trang trợ giúp với liên kết đến phiên bản Markdown của từng trang) hoặc `https://docs.youraiconnector.com/llms-full.txt` (toàn bộ tài liệu trong một tệp Markdown). Cả hai đều công khai, không cần khóa và được xây dựng lại sau mỗi lần thay đổi tài liệu.
## Tìm hoặc tạo khóa API của bạn
Khóa API mà kết nối này sử dụng nằm tại **Cài đặt → Tích hợp → Khóa API** — một phần riêng biệt, tách biệt với Webhooks. Xem [Truy cập API](api-access.md#generating-your-api-key) để biết các bước chính xác.
## Khắc phục sự cố
- **"Connection refused" hoặc "not found"** — địa chỉ bị thiếu `/mcp` ở cuối. Hãy sử dụng `https://mcp.youraiconnector.com/mcp`, không phải `https://mcp.youraiconnector.com`.
- **`Needs authentication` / 401** — khóa API của bạn bị thiếu hoặc sai. Hãy thêm lại máy chủ với `X-API-Key` hợp lệ.
- **"Could not discover OAuth settings" (ChatGPT)** — ChatGPT chỉ hỗ trợ OAuth hoặc không xác thực cho các trình kết nối tùy chỉnh, và máy chủ MCP sử dụng khóa API, vì vậy ChatGPT hiện không thể kết nối. Xem [ChatGPT](#chatgpt).
- **"Couldn't register with … sign-in service" hoặc "add an OAuth Client ID" (Claude Desktop)** — trình kết nối tùy chỉnh đã được thêm với một tùy chọn đăng nhập. Không có ID khách hàng OAuth nào để nhập: hãy xóa trình kết nối và thêm lại với **Authentication → No sign in** và khóa API của bạn dưới dạng tiêu đề yêu cầu `X-API-Key`, như trong [Claude Desktop](#claude-desktop).
- **Claude Desktop không hiển thị công cụ sau khi chỉnh sửa tệp cấu hình** — tệp cấu hình bỏ qua mục `"url"`; hãy sử dụng trình kết nối tùy chỉnh hoặc biểu mẫu `mcp-remote` trong [Claude Desktop](#claude-desktop), sau đó thoát hoàn toàn và mở lại ứng dụng.
- **Một công cụ trả về `403`** — gói dịch vụ hoặc vai trò nhóm của bạn không cho phép hành động đó; máy chủ MCP không thực thi thêm bất kỳ điều gì, đó là cùng một kiểm tra quyền như API.
- **Tool not found** — danh sách công cụ được tạo trực tiếp từ API, vì vậy nó luôn khớp với phiên bản hiện tại; hãy kết nối lại để làm mới.
- **Cảnh báo bảo mật hoặc chứng chỉ trên tên miền của riêng bạn** — việc trỏ bản ghi DNS về phía chúng tôi là chưa đủ: tên miền phụ cũng phải được xác minh trong bảng điều khiển trước khi nó có thể phục vụ kết nối bảo mật. Các đại lý White-label có thể đặt địa chỉ MCP trên tên miền của riêng họ (ví dụ: `mcp.youragency.com`) từ thẻ **Custom domain** trong **Settings → White Labeling** — trước tiên hãy thêm CNAME tại nhà đăng ký của bạn, sau đó nhập tên máy chủ vào khối **MCP domain (AI assistants)** và nhấp vào **Verify**, quy trình tương tự như các tên miền phụ có thương hiệu khác của bạn. Địa chỉ có thương hiệu sẽ bỏ qua các công cụ của đại lý; hãy tiếp tục sử dụng địa chỉ tiêu chuẩn, không có thương hiệu cho các công cụ đó. Cho đến khi địa chỉ có thương hiệu của bạn được xác minh, hãy sử dụng địa chỉ tiêu chuẩn, không có thương hiệu: nó an toàn để chia sẻ với khách hàng.
---
## Các bước tiếp theo
- [Truy cập API](api-access.md) — tạo hoặc xoay vòng khóa mà kết nối này sử dụng.
- [Webhooks](webhooks.md) — đối tác dựa trên đẩy (push-based) cho kết nối MCP dựa trên kéo (pull-based) này.