MCP

Vẫn API đó, nhưng nói với một trợ lý thay vì với một kịch bản. Client MCP chọn gọi gì trong lúc chạy, dựa trên mô tả công cụ — nên nó chạm tới đúng những gì thông tin xác thực phía sau chạm tới, và dưới mỗi công cụ là một lệnh gọi API công khai.

Chỉ một endpoint

Mọi thứ đi tới POST /v1/mcp. Không có phiên nào để mở và không có luồng nào để giữ: GET và DELETE trả về 405, và mỗi thông điệp là một yêu cầu riêng.

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

Tất cả các bản sửa đổi giao thức từ 2025-03-26 đến 2026-07-28 đều được phục vụ. Client mở đầu bằng initialize nhận được cái bắt tay nó mong đợi; client nêu phiên bản trong mỗi yêu cầu thì được phục vụ theo cách đó.

Kết nối bằng khóa API

Con đường nhanh nhất, và đúng đắn cho một công cụ bạn tự chạy. Bất kỳ khóa nào cũng hoạt động như token bearer, và bộ công cụ được đưa ra sẽ bị cắt theo phạm vi của khóa đó.

Phần lớn client nhận một khối như thế này:

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Kết nối qua OAuth

Dành cho một đầu nối trong thư mục của người khác, nơi con người không hề chạm vào khóa. Việc khám phá theo RFC 9728 và RFC 8414, client tự đăng ký bằng RFC 7591, và mọi lần cấp quyền đều dùng PKCE với S256.

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

Một lệnh gọi chưa được cấp quyền tự nói nó phải đi đâu và xin gì:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

Người phê duyệt đã đăng nhập Mosaqo, chọn không gian được áp dụng, và chỉ làm được ở nơi họ là chủ sở hữu hoặc quản trị viên — cùng ranh giới quyết định ai được cấp khóa API. Sau đó có thể ngắt trong Bulk & API.

Trợ lý có thể làm gì

Chính những phạm vi bạn đã biết, không đổi. Công cụ mà thông tin xác thực không cho phép sẽ không có trong tools/list và cũng không gọi được dù nêu đích danh — nên câu trả lời sống cho mọi kết nối chính là tools/list.

Điều nó sẽ không bao giờ chạm tới

Những gì mọi người viết trong khảo sát. reviews:read mở ra các địa điểm, khảo sát và kết quả của chúng: số lượng, điểm số, phân bố câu trả lời theo từng câu hỏi. Còn những câu mà khách đã gõ thì không được trả về ở đây, cũng như ở bất cứ nơi nào thông tin xác thực chạm tới — cùng lý do khiến các sự kiện feedback.* mang theo điểm số mà không bao giờ mang theo lời.

Xóa một mã. Tuyến REST đòi một xác nhận gõ tay vì việc phá bỏ chuyển hướng phía sau một mã đã in là không thể hoàn tác, và đó không phải xác nhận mà trợ lý thay ai đó đưa ra. Thay vào đó là lưu trữ, và việc đó đảo ngược được.

Ghi được đánh dấu là ghi. Công cụ thay đổi thứ gì đó mang readOnlyHint: false, còn lưu trữ mang destructiveHint: true — chính điều đó khiến client dừng lại và hỏi một con người trước khi chạy.