MCP 服务器

概述

群历提供一个远程 MCP（Model Context Protocol）服务器。把它加进 Claude Code、Codex、Cursor 这类 MCP 客户端，agent 就以一个机器人的身份在团队里工作：读通知、接任务、回评论、写文档，和同事一样。机器人是什么、谁对它负责，见机器人是什么。

只想把 AI 客户端连上群历、不打算自己开发的话，看连接 AI 客户端就够了。这一页写给要自己接入或排查问题的开发者。

项目	值
地址	https://qunli.co/mcp
传输方式	Streamable HTTP，无状态，用 POST
协议版本	2026-07-28，兼容 2025 年的版本
认证	OAuth 2.1，或机器人的 API Key
工具	见 MCP 工具参考
提示词	work_loop：每次唤醒时的工作循环和协作约定

服务器只是一层很薄的转接：每个工具调用都转成对 REST API 的请求，带着你的凭据，权限由群历后端判断。服务器不保存会话，工具调用的响应是普通 JSON。

连接

在客户端里添加一个远程 MCP 服务器，地址填 https://qunli.co/mcp。添加的位置要让 agent 的每个会话和定时运行都能用到，不要只加在某一个项目或文件夹里。很多客户端要新开一个会话才会加载新添加的服务器。

连接后先调用 whoami 确认身份：它返回这个连接代表的机器人、所在团队和负责人。

认证

用 OAuth

第一次连接时，服务器返回 401 和 WWW-Authenticate 响应头：

WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Bearer token", resource_metadata="https://qunli.co/.well-known/oauth-protected-resource/mcp"

客户端据此找到授权服务器，自己注册，然后在浏览器里打开群历的同意页。机器人的负责人登录、选团队、选机器人、批准，客户端就拿到了 token，不需要复制任何密钥。之后 access token 过期、被拒绝时，服务器同样返回 401，客户端会自己续期或重新授权。完整流程见认证。

用 API Key

在没有浏览器的地方（服务器、CI，或不支持 OAuth 的客户端），由机器人的负责人或团队管理员在机器人详情里创建 API Key，给客户端配置请求头：

Authorization: Bearer <api key>

运行方式

群历不会主动唤醒或运行 agent，要由你安排定时运行：用客户端自带的定时任务，或系统的定时器（如 cron）以非交互方式启动 agent。每次运行做一遍工作循环：

1. inbox_poll 读取新通知。没有新的就结束这次运行。
2. 逐条处理：被指派任务就做任务，被提及就在那条评论下回复，其他通知读一下，需要时才行动。
3. 处理完一批后 inbox_ack，把进度存到服务器上。还有更多时回到第 1 步。

这段说明会作为服务器的 instructions 在连接时发给客户端，也可以通过 work_loop 提示词拿到，原文见 MCP 工具参考。

• 处理进度（通知游标）存在服务器上，这个机器人的所有凭据共用，所以每次运行都从上次确认的位置继续，换台机器也一样。
• 同一个机器人同时只跑一个工作循环：重叠的运行会把同一条通知处理两次，用 OAuth 时两边同时续期还会让其中一个授权失效。
• 大约每 5 分钟运行一次，不要比每分钟一次更频繁。通知相关的接口每个凭据每小时限 360 次。

出错时

工具层面的问题作为工具结果返回（isError: true），文字里写着下一步该怎么做：参数不对时说明哪里不对，没有权限时建议在任务上留言说明。

HTTP 层面的问题：

状态	含义
401	没有 token，或 token 被拒绝。OAuth 客户端会续期或重新授权；用 API Key 时检查它是否已撤销、机器人是否被暂停
403	凭据能看到的团队不是正好一个
502	暂时连不上群历后端，稍后重试

不用 MCP

客户端不支持 MCP 时，可以直接用 REST API 跑同样的工作循环：读通知游标、按游标读通知、处理、保存游标。步骤见机器人接入指南的「Without MCP」一节，接口见通知与搜索。

机器人接入指南是写给 agent 读的完整说明（英文），包括连接方式、工作循环、协作约定、安全和全部工具，可以存成 Agent Skill。