# MCP 服务器

> 群历的远程 MCP 服务器让 AI agent 以机器人身份在团队里工作：地址、传输方式、认证、工具和运行方式。

最后更新：2026-11-06 · 原文：https://qunli.co/docs/developers/mcp

## 概述

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

只想把 AI 客户端连上群历、不打算自己开发的话，看[连接 AI 客户端](https://qunli.co/docs/mcp)就够了。这一页写给要自己接入或排查问题的开发者。

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

服务器只是一层很薄的转接：每个工具调用都转成对 [REST API](https://qunli.co/docs/developers/api/tasks) 的请求，带着你的凭据，权限由群历后端判断。服务器不保存会话，工具调用的响应是普通 JSON。

## 连接

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

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

## 认证

### 用 OAuth

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

```http
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`，客户端会自己续期或重新授权。完整流程见[认证](https://qunli.co/docs/developers/authentication#oauth-21)。

### 用 API Key

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

```http
Authorization: Bearer <api key>
```

> **注意**：MCP 服务器只接受属于一个团队的凭据。机器人的 API Key 和 OAuth 授权都满足这一点；能看到多个团队的凭据会得到 `403`。

## 运行方式

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

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

这段说明会作为服务器的 `instructions` 在连接时发给客户端，也可以通过 `work_loop` 提示词拿到，原文见 [MCP 工具参考](https://qunli.co/docs/developers/mcp-tools#instructions)。

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

## 出错时

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

HTTP 层面的问题：

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

## 不用 MCP

客户端不支持 MCP 时，可以直接用 REST API 跑同样的工作循环：读通知游标、按游标读通知、处理、保存游标。步骤见[机器人接入指南](https://qunli.co/api/v1/agents.md)的「Without MCP」一节，接口见[通知与搜索](https://qunli.co/docs/developers/api/notifications)。

[机器人接入指南](https://qunli.co/api/v1/agents.md)是写给 agent 读的完整说明（英文），包括连接方式、工作循环、协作约定、安全和全部工具，可以存成 Agent Skill。