diff --git a/xiaoqu-agent-service/doc/mcp-external-integration-spec.md b/xiaoqu-agent-service/doc/mcp-external-integration-spec.md
new file mode 100644
index 0000000..c144ca4
--- /dev/null
+++ b/xiaoqu-agent-service/doc/mcp-external-integration-spec.md
@@ -0,0 +1,140 @@
+# 小趣 MCP 外部接入规范
+
+> 版本：v1.0（2026-09-15）
+> 适用对象：CRM 等外部系统的后端集成方
+> 状态：当前生效。认证换发流程（第 3 节）为小趣自定义扩展，后续可能升级为 OAuth 2.1 / MCP 标准授权，届时本规范会发新版并保留兼容期。
+
+## 1. 服务边界
+
+小趣 MCP 只做三件事：**供数据、供身份、守权限**。
+
+- 供数据：查询工具（QUERY）+ 增量同步工具（SYNC），保证准确、一致、可恢复
+- 供身份：Token 签发 / 吊销 / 自检
+- 守权限：服务 Token 按授权 scope 白名单限工具，个人 Token 实时 ACL 行过滤
+
+到期规则计算、AI 决策、消息推送、经营事项流转**不属于** MCP 职责，由接入方或小趣 AI 系统自行实现，MCP 不提供也不预留相关字段。
+
+## 2. 接入端点与协议
+
+| 项 | 值 |
+|---|---|
+| MCP 端点（生产） | `https://agent.ququclean.com/mcp` |
+| 传输协议 | MCP Streamable HTTP（JSON-RPC 2.0） |
+| 协议版本头 | `MCP-Protocol-Version: 2025-06-18` |
+| 响应格式 | SSE（`text/event-stream`），取 `data:` 行解析为 JSON-RPC 消息 |
+| 会话 | `initialize` 响应头返回 `Mcp-Session-Id`，后续请求必须携带 |
+
+### 2.1 标准握手序列
+
+```text
+POST /mcp  initialize（JSON-RPC，带 id）
+  ← 响应头取 Mcp-Session-Id，data: 行为 initialize 结果
+POST /mcp  notifications/initialized（无 id，带 Mcp-Session-Id）
+  ← 202，无响应体
+POST /mcp  tools/list        # 自动发现工具及输入 JSON Schema
+POST /mcp  tools/call        # 按 Schema 调用具体工具
+```
+
+请求统一头：
+
+```http
+Authorization: Bearer <xqak-...>
+Content-Type: application/json
+Accept: application/json, text/event-stream
+MCP-Protocol-Version: 2025-06-18
+Mcp-Session-Id: <initialize 返回的会话 ID>
+X-Mcp-Schema-Version: 2
+```
+
+注意：`notifications/initialized` 生效后再发 `tools/list`，否则偶发空响应，重试即可。
+
+## 3. 认证与凭证管理（自定义扩展）
+
+### 3.1 两类凭证
+
+| 凭证 | 形态 | 用途 | 获取方式 |
+|---|---|---|---|
+| 服务密钥 `X-Open-Key` | `xqok-...` | 换取访问 Token，**不是** MCP Token | 管理员在管理后台「服务密钥」页创建，明文只展示一次 |
+| 访问 Token | `xqak-...` | 放进 `Authorization: Bearer` 调 `/mcp` | 用服务密钥调 ensure 接口换取，长期有效 |
+
+### 3.2 换取 Token
+
+```http
+POST https://agent.ququclean.com/api/open/token/ensure
+X-Open-Key: <服务密钥>
+Content-Type: application/json
+
+{"scopeCode":"sync","principalType":"service","serviceName":"<你的系统名>"}
+```
+
+响应 `token` 字段即访问 Token。该接口幂等：同一 subject 重复调用返回同一 Token。
+
+个人 Token（前台点查场景）：同接口传 `{"mobile": "<人员手机号>"}`，幂等返回该人员的个人 Token（`user_delegated`），人员停用后 60 秒内自动失效。
+
+### 3.3 凭证安全要求
+
+- 服务密钥与 Token 只允许存接入方后端的密钥管理设施或环境变量，**禁止**下发浏览器/App、禁止写入日志、禁止提交代码库
+- 密钥泄露：通知小趣管理员在管理后台执行「轮换」（旧密钥立即失效）或「吊销」
+- 数据库只存密钥哈希，创建/轮换弹窗关闭后明文不可找回
+
+## 4. 工具分类与调用约定
+
+### 4.1 工具发现
+
+`tools/list` 返回当前 Token 可见的全部工具及入参 JSON Schema。**可见性由 Token 绑定的 scope 白名单决定**——未授权的工具不出现在列表中，接入方应按 `tools/list` 结果动态适配，不要硬编码工具清单。
+
+### 4.2 统一输出信封
+
+所有工具返回 `structuredContent`，`X-Mcp-Schema-Version: 2` 时为新信封：
+
+```json
+{ "schema_version": 2, "request_id": "...", "data": { ... } }
+```
+
+- 不带该请求头返回 v1 老结构（兼容期内有效）
+- `request_id` 必须记入接入方日志，双向排查用；Token 与手机号明文不落日志
+
+### 4.3 通用入参约束
+
+- 所有工具**禁止传 `tenant_id` / `scope`**，租户从 Token 推导，传了返回 `PERMISSION_DENIED`
+- 分页类工具 `limit` 上限 200，超出截断并在响应带 notice
+
+## 5. 错误码与重试规则
+
+| 错误码 | 含义 | 接入方动作 |
+|---|---|---|
+| `UNAUTHENTICATED` | Token 吊销 / 人员停用 | 重新 ensure 取 Token；仍失败则告警人工介入 |
+| `PERMISSION_DENIED` | 工具不在 Token scope 白名单，或传了 tenant_id | 检查绑定与入参，**不要**重试 |
+| `RATE_LIMITED` | 触发限流 | 指数退避重试（1s/2s/4s…上限 60s） |
+| `SYNC_CURSOR_EXPIRED` | 同步快照/游标过期或被篡改 | 清空本地镜像，`syncToken=null` 全量重建 |
+| `INVALID_ARGUMENT` | 入参不符合 Schema | 修正后重发，不要原样重试 |
+
+限流分档：SYNC 工具独立配额档，与 QUERY 互不占配额。
+
+## 6. 增量同步协议（SYNC 工具）
+
+工具：`users.changes.list` / `properties.changes.list` / `contracts.changes.list`。
+
+入参仅三个：`syncToken`、`cursor`、`limit`。
+
+协议语义：
+
+- **快照**：每轮同步签发 `snapshot_id` + `data_cutoff_at`，同一快照内翻页结果稳定
+- **游标**：页内 `(modify_time, id)` 复合游标；`has_more=true` 时带 `next_cursor` 翻页
+- **续传**：仅末页（`has_more=false`）签发 `next_sync_token`；中断后从本地保存的 `sync_token + cursor` 继续，不重不漏
+- **tombstone**：`deleted_at` 非空为删除标记，本地镜像应标记删除
+- **版本字段**：`version` 由 `modify_time` 派生，仅用于调试核对，禁止用作并发控制
+
+接入方必须持久化每页的 `sync_token + cursor`（断点恢复），实现 `SYNC_CURSOR_EXPIRED` 全量重建分支，并在扫描启动前用 `integration.context.get` 校验 `principal_type=tenant_service` 且 capability 含 SYNC，拿错个人 Token 时拒绝执行扫描。
+
+## 7. 交付物与责任划分
+
+| 小趣侧交付 | 接入方自负责 |
+|---|---|
+| 本规范（契约定义） | MCP 客户端实现（可用任意标准 MCP Client SDK） |
+| 管理后台服务密钥创建/轮换/吊销 | 密钥与 Token 的安全存储 |
+| 工具清单及入参 Schema（`tools/list` 自动发现） | 本地镜像 upsert / 逻辑删除 |
+| 错误码语义与限流档位 | 定时任务调度、游标持久化、重试退避 |
+| `request_id` 双侧排查支持 | 业务规则、AI 决策、推送 |
+
+详细逐步接入示例（含报文样例与伪代码）见《CRM 接入手册》`doc/crm-integration-guide.md`。