REST 首聊与 MCP：OAuth token 与 Streamable HTTP

你将得到什么

• 一小时有效的 REST access_token（client_credentials）
• 一次成功的 GET /agents 与 POST /agents/{id}/chat JSON 响应
• 一份可粘贴的 MCP 客户端配置（Streamable HTTP + Bearer）

开始前准备

1. 打开 Communicate 应用，选中 workspace，创建 API key，勾选至少：
   • agents:read — 列出 Agent
   • chat:write — 向 Agent 发消息
     创建时会显示 Client ID（key ID）与一次性 ck_ Client secret——只显示一次，Communicate 只存 hash。
2. 本机已装 curl 与 jq。
3. 工作区内至少有一个状态为 active 的 Agent（可在 UI 或课时 1 CLI 创建）。

警告（官方）：把 API key / secret 当作服务端密钥；不要放进浏览器、移动端、公开仓库、日志或 URL。

核心事实

也可直接用 Authorization: Bearer ck_... 调 REST（权限=该 key 全部 scopes）；MCP 不接受长期 ck_，必须换短期 OAuth token，且 resource=https://app.communicate.so/mcp。

步骤 1：换 REST access_token

export COMMUNICATE_CLIENT_ID="your_key_id"
export COMMUNICATE_CLIENT_SECRET="ck_your_secret"

export COMMUNICATE_ACCESS_TOKEN="$(curl -sS \
  -u "$COMMUNICATE_CLIENT_ID:$COMMUNICATE_CLIENT_SECRET" \
  https://app.communicate.so/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=agents%3Aread%20chat%3Awrite" \
  | jq -r '.access_token')"

echo "token_len=${#COMMUNICATE_ACCESS_TOKEN}"

对照结果：

• jq 取出非空 access_token
• 典型响应字段含 token_type: Bearer、expires_in: 3600、scope
• token_len 明显大于 0（不要把完整 token 打印到共享屏幕）

请求的 scope 必须是创建 key 时权限的子集。吊销/收窄 key 会立即影响已签发 token。

步骤 2：列出 workspace Agents

curl -sS https://app.communicate.so/api/v1/agents \
  -H "Authorization: Bearer $COMMUNICATE_ACCESS_TOKEN" | jq .

对照结果：JSON 列表中能看到你的 Agent；记下一条 active 的 agent_id（字段名以响应为准，常见为 id）。

缺/错 Bearer 时官方返回 401，带 WWW-Authenticate 与结构化错误，例如 {"error":"Missing API key","code":"api_key_missing"}。

步骤 3：向 active Agent 发首条 chat

把下面的 agent_id 换成上一步的真实 ID：

curl -sS https://app.communicate.so/api/v1/agents/agent_id/chat \
  -H "Authorization: Bearer $COMMUNICATE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"How do I reset my password?"}' | jq .

对照结果：一次返回完整 JSON（官方明确 不流式），内容为接地知识库的答复结构（含引用/会话字段时以实际 OpenAPI 为准）。若 Agent 未激活或 ID 错误，会得到 4xx——先回步骤 2 核对状态。

OpenAPI 契约：https://app.communicate.so/api/v1/openapi.json。

步骤 4：申请 MCP 专用 token

MCP 与 REST 的 token 资源绑定不同。按官方 MCP 页：

export COMMUNICATE_MCP_TOKEN="$(curl -sS \
  -u "$COMMUNICATE_CLIENT_ID:$COMMUNICATE_CLIENT_SECRET" \
  https://app.communicate.so/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=agents%3Aread" \
  -d "resource=https%3A%2F%2Fapp.communicate.so%2Fmcp" \
  | jq -r '.access_token')"

echo "mcp_token_len=${#COMMUNICATE_MCP_TOKEN}"

对照结果：非空 token；约一小时后需重换再连 MCP。MCP token 当前只接受 agents:read。聊天请继续用带 chat:write 的 REST token。

OAuth 发现文档：

• https://app.communicate.so/.well-known/oauth-protected-resource/mcp
• https://app.communicate.so/.well-known/oauth-authorization-server/api/v1

步骤 5：配置 MCP 客户端（Streamable HTTP）

通用 JSON（Bearer 用环境变量注入，不要把 secret/token 写进会提交的配置文件）：

{
  "mcpServers": {
    "communicate": {
      "url": "https://app.communicate.so/mcp",
      "headers": {
        "Authorization": "Bearer ${COMMUNICATE_MCP_TOKEN}"
      }
    }
  }
}

Codex 等价（官方 TOML 示例）：

[mcp_servers.communicate]
url = "https://app.communicate.so/mcp"
bearer_token_env_var = "COMMUNICATE_MCP_TOKEN"

在 Cursor / Claude Code 等支持 Streamable HTTP MCP 的客户端中粘贴等价配置后：

1. 确保 shell/会话已 export COMMUNICATE_MCP_TOKEN=...
2. 重载 MCP / 重启客户端
3. 对照：应能发现只读工具 communicate_list_agents，调用后返回当前 workspace 的 Agent 列表

本课检查清单

• 换到 REST COMMUNICATE_ACCESS_TOKEN（含 agents:read chat:write）
• GET /agents 看到 active Agent
• POST .../chat 返回完整 JSON 答复
• 换到 COMMUNICATE_MCP_TOKEN（resource=.../mcp）
• 客户端出现 communicate_list_agents

安全收尾

unset COMMUNICATE_CLIENT_SECRET COMMUNICATE_ACCESS_TOKEN COMMUNICATE_MCP_TOKEN

需要帮助可邮件官方：communicate@support.communicate.so。能力以线上 capabilities 为准。