统一登录服务 MCP 文档

文档信息

项目	说明
文档版本	v1.2.0
最后更新	2026-01-12
文档状态	正式版
服务名称	统一登录服务
服务标识	MCP-Server

1. 服务概述

统一登录服务对外提供 自然人登录、托管登录、人脸认证、产品相关 等能力，统一通过 MCP 协议调用。用户只需选择正确的服务路径（mount path）与工具名称（tool），并在请求参数中携带 client_appkey/client_secret 即可完成登录与关联业务。

基础 URL（生产）：https://mcp.qixiangyun.com

2. 服务路径与工具总览

服务名称	Mount Path	核心工具（对外名称 / 中文说明）
自然人登录服务	`/mcp/login`	`natural_person_login_step1`（自然人登录获取短信验证码）, `natural_person_login_step2`（自然人登录上传短信验证码）, `query_natural_enterprise_list`（查询自然人企业列表-自然人）, `query_enterprises_by_individual`（查询自然人企业列表-托管）
托管登录服务	`/mcp/request_managed_login`	`send_managed_tax_app_login_sms_code_auto`（发送托管登录短信验证码）, `upload_managed_tax_app_login_sms_code_auto`（上传托管登录短信验证码）
人脸服务	`/mcp/face`	`get_face_qr_code_auto`（获取税务APP人脸二维码）, `get_face_auth_result_auto`（查询税务APP人脸结果）, `get_gs_face_qr_code_auto`（获取个税APP人脸二维码）, `get_gs_face_auth_result_auto`（查询个税APP人脸结果）
产品相关服务	`/mcp/products`	`order_products_auto`（产品订购）, `creation_modification_accounts`（通用账号创建/修改）, `verify_tax_app_quick_login`（校验税务APP快速登录）

说明：统一网关同时提供 SSE 与 HTTP Streamable 两种传输模式，请参考《MCP服务文档》的调用方式章节。

3. 鉴权方式与安全说明

所有工具调用必须包含 client_appkey 与 client_secret。

推荐使用注入脚本从本地 .env 读取后自动注入，避免每次手工传参。

自然人登录密码支持明文传入

请勿在日志中输出用户身份证号、手机号、税号等敏感信息。

4. 快速开始

4.1 自然人登录（两步验证）

4.2 托管登录（发送/上传短信验证码）

5. 接口说明

5.1 自然人登录服务（/mcp/login）

5.1.1 natural_person_login_step1

功能说明：自然人APP登录第一步：尝试自动登录或获取验证码。若 cookie 未过期会直接成功，否则下发短信验证码并返回 taskId。

必填参数：

area_code / areaCode: 地区编码，例如 3100

gryhm: 个人用户名/账号（通常为手机号或身份证号）

gryhmm: 个人密码（明文即可，服务端自动 RSA 加密）

可选参数：

sjhm: 手机号（默认使用 gryhm）

client_appkey / client_secret

返回示例（需要验证码）：

{
  "code": "2000",
  "success": true,
  "message": "登录需要短信验证码，验证码已发送到 132****5344",
  "data": {
    "taskId": "1864275***********",
    "mobile": "132********",
    "msg": "验证码发送成功"
  }
}

5.1.2 natural_person_login_step2

功能说明：自然人APP登录第二步：上传短信验证码完成登录。

必填参数：

task_id: 第一步返回的任务 ID

sms_code: 短信验证码

可选参数：

client_appkey / client_secret

5.1.3 query_natural_enterprise_list

功能说明：查询自然人 APP 关联的企业列表（需地区编码）。

必填参数：

gryhm:个人用户名

gryhmm:个人用户名密码

areaCode :地区码

可选参数：

sjhm

client_appkey / client_secret

5.1.4 query_enterprises_by_individual

功能说明：查询自然人在税局网页端绑定并启用的企业列表（无需地区编码）。

5.4.1 order_products_auto

功能说明：产品订购服务，返回企业关联唯一标识 aggOrgId。

必填参数：

nsrsbh: 税号

aggOrgName: 企业名称

dq: 地区编码

productCodeList: 产品码（英文逗号分隔或数组）

可选参数：

client_appkey / client_secret

5.4.2 creation_modification_accounts

功能说明：通用账号创建/修改。

必填参数：

aggOrgId:企业id

dlfs:登录方式

gryhm:个人用户名

gryhmm:个人用户密码

sflx:身份类型

sjhm:手机号码

可选参数：

proxyNsrsbh:代理机构税号

client_appkey / client_secret

5.4.3 verify_tax_app_quick_login

功能说明：校验税务 APP 是否支持快速登录。

必填参数：

aggOrgId:企业id

可选参数：

account_id多账户id

client_appkey / client_secret

6. 常见问题

Q1：为什么提示缺少 client_appkey/client_secret？
A：请确认已通过注入脚本或手工参数传入。建议使用统一注入脚本自动补齐。

Q2：area_code 与 areaCode 都能用吗？
A：两种写法都支持，推荐使用 areaCode，保持一致性。

Q3：自然人企业列表有两个工具，怎么选？
A：

query_natural_enterprise_list：APP 关联企业列表（需要 areaCode）

query_enterprises_by_individual：税局网页端绑定企业列表（不需要 areaCode）

统一登录服务

统一登录服务 MCP 文档#

文档信息#

目录#

1. 服务概述#

2. 服务路径与工具总览#

3. 鉴权方式与安全说明#

4. 快速开始#

4.1 自然人登录（两步验证）#

4.2 托管登录（发送/上传短信验证码）#

5. 接口说明#

5.1 自然人登录服务（/mcp/login）#

5.1.1 natural_person_login_step1#

5.1.2 natural_person_login_step2#

5.1.3 query_natural_enterprise_list#

5.1.4 query_enterprises_by_individual#

5.2 托管登录服务（/mcp/request_managed_login）#

5.2.1 send_managed_tax_app_login_sms_code_auto#

5.2.2 upload_managed_tax_app_login_sms_code_auto#

5.3 人脸服务（/mcp/face）#

5.3.1 get_face_qr_code_auto#

5.3.2 get_face_auth_result_auto#

5.3.3 get_gs_face_qr_code_auto#

5.3.4 get_gs_face_auth_result_auto#

5.4 产品相关服务（/mcp/products）#

5.4.1 order_products_auto#

5.4.2 creation_modification_accounts#

5.4.3 verify_tax_app_quick_login#

6. 常见问题#

统一登录服务 MCP 文档

文档信息

目录

1. 服务概述

2. 服务路径与工具总览

3. 鉴权方式与安全说明

4. 快速开始

4.1 自然人登录（两步验证）

4.2 托管登录（发送/上传短信验证码）

5. 接口说明

5.1 自然人登录服务（/mcp/login）

5.1.1 natural_person_login_step1

5.1.2 natural_person_login_step2

5.1.3 query_natural_enterprise_list

5.1.4 query_enterprises_by_individual

5.2 托管登录服务（/mcp/request_managed_login）

5.2.1 send_managed_tax_app_login_sms_code_auto

5.2.2 upload_managed_tax_app_login_sms_code_auto

5.3 人脸服务（/mcp/face）

5.3.1 get_face_qr_code_auto

5.3.2 get_face_auth_result_auto

5.3.3 get_gs_face_qr_code_auto

5.3.4 get_gs_face_auth_result_auto

5.4 产品相关服务（/mcp/products）

5.4.1 order_products_auto

5.4.2 creation_modification_accounts

5.4.3 verify_tax_app_quick_login

6. 常见问题