文档› MCP Server› 概览 & Endpoint

MCP Server 接入

愉悦查 MCP Server 基于 MCP 1.21 streamableHttp 协议，同一 Endpoint 同时处理 POST（工具调用）和 GET / SSE（流式响应）。支持 Claude / Cursor / Trae / WorkBuddy / 蚂蚁百宝箱等任意 MCP Client 直接接入，无需额外适配。

Endpoint 地址

ENDPOINTS
# 测试环境（开发 / 调试使用）
https://yuyue.cn/mcpadmin/mcp

# 正式环境（生产接入使用）
https://www.yuyuecha.com/mcpadmin/mcp
ℹ
同一 Endpoint 兼容 POST（发起工具调用）和 GET / SSE（接收流式响应），符合 MCP 1.21 streamableHttp 规范，无需配置两个地址。测试环境数据为沙盒数据，不产生真实费用。

快速接入（3 步）

01
STEP · 01

添加配置

在 MCP Client 的配置文件中添加 yuyuecha Server，填入 API Key。

type: streamableHttp
02
STEP · 02

验证工具列表

调用 tools/list 确认 10 个工具全部就绪。

→ 10 tools ready ✓
03
STEP · 03

调用工具

公开工具无需鉴权，受控工具需 API Key，订单类还需授权票据。

call: product.recommend
Step 1 — 添加到 MCP Client 配置
JSON · mcp_config.json
{
  "mcpServers": {
    "yuyuecha": {
      "type":    "streamableHttp",
      "url":     "https://www.yuyuecha.com/mcpadmin/mcp",
      "headers": {
        "X-Yuyuecha-API-Key": "yyc_xxxxxxxxxxxxxxxx"
      }
    }
  }
}
Step 2 — 验证工具列表
MCP REQUEST
tools/list

# 预期响应（共 10 个工具）
{
  "tools": [
    { "name": "product.list",         "auth": "none"             },
    { "name": "product.detail",       "auth": "none"             },
    { "name": "product.recommend",    "auth": "none"             },
    { "name": "report.sample",        "auth": "none"             },
    { "name": "report.sample_explain", "auth": "none"             },
    { "name": "lead.create",          "auth": "none"             },
    { "name": "consent.precheck",     "auth": "api_key"          },
    { "name": "report.order_create",  "auth": "api_key+consent"  },
    { "name": "report.status",        "auth": "api_key"          },
    { "name": "report.summary",       "auth": "api_key"          }
  ]
}
Step 3 — 调用工具示例
MCP REQUEST · product.recommend
tools/call  product.recommend
{
  "scenario": "公司新招家政阿姨，需要入户前背景核查"
}

# 响应
{
  "product":   "家政风险报告",
  "code":      "homeservice",
  "price":     39.9,
  "reason":    "覆盖违法犯罪、行政处罚、失信被执行人等核心风险",
  "next_tool": "consent.precheck"
}

工具清单

10 个工具分两类：公开工具无需鉴权，任何人可调用；受控工具需要 API Key，订单类还需授权票据（consent token）。

工具名说明鉴权要求超时
product.list列出 6 大产品基本信息公开3s
product.detail返回单个产品详情公开3s
product.recommend按场景推荐最适合的产品公开5s
report.sample返回脱敏样例报告公开5s
report.sample_explain解读样例报告字段含义公开5s
lead.create创建留资线索（需脱敏处理）公开8s
consent.precheck授权用途前置校验，返回 consent tokenAPI Key8s
report.order_create创建真实报告订单（异步，产生费用）Key + Consent异步
report.status查询订单状态API Key5s
report.summary返回脱敏报告摘要API Key8s
⚠
调用 report.order_create 会产生真实费用并消耗用户授权额度。必须先调用 consent.precheck 取得 consent token，否则返回 CONSENT_MISSING (403)。订单创建后不支持撤销，请在测试服验证完整流程后再切换正式服。

鉴权方式

推荐使用 HTTP Header 传递 API Key。API Key 在运营后台（yuyuecha.com/mcpadmin）申请，按租户隔离，支持多 Key 管理和轮换。

HTTP HEADERS
# 推荐（API Key Header）
X-Yuyuecha-API-Key: yyc_xxxxxxxxxxxxxxxx

# 备用（Bearer JWT）
Authorization: Bearer <jwt_token>

# 订单类工具额外携带 consent token
X-Yuyuecha-API-Key: yyc_xxxxxxxxxxxxxxxx
X-Consent-Token:    cst_xxxxxxxx   # consent.precheck 返回
✓
API Key 格式：yyc_ 前缀 + 32 位随机字符。密钥轮换：生成新 Key → 灰度切换流量 → 回收旧 Key，全程无中断。

错误码参考

HTTP错误码含义处理建议
401AUTH_REQUIRED未携带 API Key / JWT检查请求 Header
403AUTH_INVALID鉴权无效或已吊销重新申请 API Key
403CONSENT_MISSING缺少授权票据先调用 consent.precheck
400INVALID_PARAM参数格式错误检查入参类型和必填项
422PURPOSE_INVALID用途不合规联系合规团队确认场景
404ORDER_NOT_FOUND订单不存在检查 order_id 是否正确
429RATE_LIMITED触发限流降低请求频率，见限流策略
504DATA_SOURCE_TIMEOUT数据源响应超时3-5 秒后重试，最多 3 次
500INTERNAL_ERROR其他内部错误携带 request_id 联系支持

限流策略

限流层级限制超限响应备注
全局网关240 req/min429 RATE_LIMITED所有 Key 共享
单 API Key60 req/min单租户上限
受控工具（单 Key）20 req/minorder_create 等高风险工具
ℹ
蚂蚁应用模板硬门槛：公开工具 P90 首 token ≤ 10s，受控工具 P90 ≤ 15s。建议公开工具超时设置 ≤ 8s，受控工具异步处理。

调用受控工具（创建真实报告）前，必须完成授权链路。以下是完整的四步流程：

完整授权流程示例
# Step 1: 推荐产品
tools/call  product.recommend
{ "scenario": "入职背调" }
→ { "code": "backgroundcheck", "next_tool": "consent.precheck" }

# Step 2: 前置授权校验（需用户明确同意）
tools/call  consent.precheck
{
  "product":  "backgroundcheck",
  "purpose":  "入职前背景核查",
  "operator": "人力资源部"
}
→ { "consent_token": "cst_abc123", "expires_in": 300 }

# Step 3: 创建报告订单
tools/call  report.order_create
{
  "product":       "backgroundcheck",
  "consent_token": "cst_abc123",
  "subject_name":  "张三",
  "subject_id":    "110101****"
}
→ { "order_id": "ord_xyz789", "status": "pending", "eta": "8s" }

# Step 4: 查询报告摘要（报告就绪后）
tools/call  report.summary
{ "order_id": "ord_xyz789" }
→ { "risk_level": "低风险", "summary": "...", "report_url": "..." }

数据脱敏规则

所有出站响应均经过脱敏中间件处理，以下字段类型自动脱敏：

字段类型脱敏规则示例
身份证号前 6 位 + 后 4 位，中间脱敏110101****1234
手机号前 3 位 + 后 4 位，中间脱敏138****0000
银行卡号后 4 位可见，其余脱敏****1234
姓名仅展示姓氏 + * 号张**
⚠
脱敏失败的响应会被强制拦截并记录到合规审计日志，不会返回给调用方。如需完整数据展示，请在已获授权的前端界面内展示，不能通过 Agent 消息直接传递原始个人信息。
← 上一页
平台概览
下一页 →
CLI SDK 文档