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.* 事件只携带评分、从不携带原话。

删除二维码。 REST 路由要求手动输入确认，因为销毁印刷码背后的跳转无法撤销，而这不是助手能代人给出的确认。取而代之提供归档，归档可以撤销。

写操作被标记为写操作。会改变东西的工具带 readOnlyHint: false，归档带 destructiveHint: true——正是这一点让客户端在执行前停下来问人。