MCP

同一套 API，面向助理而非面向情境。MCP 用戶端在執行時依工具描述決定要呼叫什麼——因此它能觸及的，正是其背後憑證能觸及的，而每個工具底下都是一次公開 API 呼叫。

只有一個端點

一切都送往 POST /v1/mcp。沒有工作階段要開，也沒有串流要維持：GET 與 DELETE 回 405，每則訊息都是獨立請求。

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

從 2025-03-26 到 2026-07-28 的協定修訂版全部支援。以 initialize 開場的用戶端會得到它預期的握手；在每個請求裡宣告版本的，就照那種方式處理。

用 API 金鑰連接

最快的路徑，也是你自己執行的工具該走的路徑。任何金鑰都可當作 bearer 權杖，而提供的工具會裁剪到該金鑰的權限範圍。

多數用戶端接受這樣的設定區塊：

{
  "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" }'

透過 OAuth 連接

適用於別人目錄裡的連接器，人從不經手金鑰。探索遵循 RFC 9728 與 RFC 8414，用戶端依 RFC 7591 自行註冊，每次授權都使用帶 S256 的 PKCE。

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

未授權的呼叫會自己說明去哪裡、求什麼：

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"

批准的人已登入 Mosaqo，選擇這適用於哪個工作區，而且只能在自己是擁有者或管理員的地方這麼做——與決定誰可以簽發 API 金鑰的是同一條線。之後可在 Bulk & API 中斷開。

助理能做什麼

就是你已熟悉的那些權限範圍，沒有變化。憑證不允許的工具不會出現在 tools/list 裡，直接點名也呼叫不了——所以任何連線的即時答案就是 tools/list 本身。

它永遠觸及不到什麼

人們在問卷裡寫下的內容。 reviews:read 打開你的地點、問卷及其表現：數量、評分、每道題的分佈。訪客敲下的句子在這裡不會被回傳，在任何憑證可達之處也一樣——正如 feedback.* 事件只攜帶評分、從不攜帶原話。

刪除 QR Code。 REST 路由要求手動輸入確認，因為銷毀印刷碼背後的轉址無法復原，而這不是助理能代人給出的確認。取而代之提供封存，封存可以復原。

寫入被標記為寫入。會改變東西的工具帶 readOnlyHint: false，封存帶 destructiveHint: true——正是這一點讓用戶端在執行前停下來問人。