接入文档 · 羽山数据 MCP

羽羽山数据 MCP接入文档

接入文档 Streamable HTTP · MCP

还没有 Token？先登录控制台创建，明文只显示一次。下面的示例把 <TOKEN> 换成自己的即可直接运行。

1接入信息

接入地址	https://mcp.usendata.com/mcp
传输方式	Streamable HTTP（单端点，POST 收发）
协议版本	2025-06-18
认证方式	Authorization: Bearer <token>
必带请求头	Accept: application/json, text/event-stream
内容类型	Content-Type: application/json
会话标识	initialize 的响应头 mcp-session-id，后续请求需原样带回

Token 在「Token 管理」里创建，明文只显示一次。只需要 token，不需要再传 user_id 或 api_key——服务端会根据 token 自动确定数据权限。

2客户端配置

下面几份配置按客户端类型挑一份即可，把 <TOKEN> 换成你自己的 token。

WorkBuddy

配置文件 ~/.workbuddy/mcp.json（Windows 为 C:\Users\<用户名>\.workbuddy\mcp.json），保存后在连接器里重连。

~/.workbuddy/mcp.json

{
  "mcpServers": {
    "yushan-mcp": {
      "type": "streamableHttp",
      "url": "https://mcp.usendata.com/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

Claude Code

终端命令

claude mcp add --transport http yushan \
  https://mcp.usendata.com/mcp \
  --header "Authorization: Bearer <TOKEN>"

# 查看是否添加成功
claude mcp list

# 需要删除时
claude mcp remove yushan

Cursor、Cline、Cherry Studio 等通用 JSON 客户端

mcpServers 配置（字段名略有差异，实质相同）

{
  "mcpServers": {
    "yushan": {
      "url": "https://mcp.usendata.com/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

VS Code（GitHub Copilot MCP）

VS Code 用的是 servers 键，并且要显式写 "type": "http"。

.vscode/mcp.json 或用户设置

{
  "servers": {
    "yushan": {
      "type": "http",
      "url": "https://mcp.usendata.com/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

Claude Desktop 等只支持本地 stdio 的客户端

需要用 mcp-remote 把远程 HTTP 转成本地 stdio，第一次运行会联网下载依赖（需要 Node.js）。

claude_desktop_config.json

{
  "mcpServers": {
    "yushan": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.usendata.com/mcp",
        "--header", "Authorization: Bearer <TOKEN>"
      ]
    }
  }
}

3手动调用（curl 全流程）

排查问题、或者想确认 token 是否可用时，直接用下面这段脚本。三步都不能少： 初始化 → 拿 session → 再调工具。

bash

TOKEN="<TOKEN>"
BASE="https://mcp.usendata.com/mcp"

# 1) 初始化，从响应头里取 mcp-session-id
curl -s -D /tmp/h.txt -o /dev/null -X POST "$BASE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"my-client","version":"1.0"}}}'

SID=$(grep -i "mcp-session-id" /tmp/h.txt | tr -d '\r' | cut -d' ' -f2)
echo "session=$SID"

# 2) 列出工具（后续每个请求都要带这个 session 头）
curl -s -X POST "$BASE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3) 调用工具
curl -s -X POST "$BASE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"query_company_basic_info",
                 "arguments":{"entname":"深圳市腾讯计算机系统有限公司"}}}'

响应是 SSE 格式，正文长这样，取 data: 后面那行 JSON 才是结果：

响应示例

event: message
data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}],"isError":false}}

标准客户端会自动发送 notifications/initialized 通知，手工 curl 可以省略，不影响后续调用。会话长时间空闲或服务重启后会失效，此时重新 initialize 拿新 session 即可。

4工具清单

参数名大小写不统一（有的 entname、有的 entName、有的 name），照抄下表，写错会报 Field required。全表共 13 个工具：除模糊查询与地址解析外，其余都需要企业全名；工商与境外主体查询也可用统一信用代码/登记号直接定位。

工具	参数	说明
fuzzy_query_company	keyWord	按关键词模糊查企业，返回候选列表。查全名用这个，也是所有查询的入口
query_company_basic_info	entname	工商基本信息：法人、注册资本、成立日期、地址、经营范围、股东等
verify_company_name_and_president	operName entName	核验「法人姓名 + 企业名」是否一致，返回 0 表示一致、1 表示不一致
query_company_change_records	entName	工商变更记录
query_company_overseas_investments	entName	对外投资：被投企业、出资金额、持股比例
query_company_trademark_list	entName	商标列表及状态
query_company_patent_list	entName	专利列表
query_company_software_copyright_info	entName	软件著作权登记信息
query_company_court_litigation_related_info	name	司法涉诉：裁判文书、开庭公告、失信、被执行、终本、法院公告等
query_company_abnormal_business_operation	keyWord	经营异常名录信息
query_company_serious_violation_blacklist	entname creditcode regno orgcode enttype	严重违法失信（黑名单）：列入/移出日期、事由、决定机关，同时返回企业档案。前四者至少传一个，优先传信用代码；enttype 可选，1=企业 2=个体。未命中返回空结构，属正常业务结果
query_company_global_info	BusinessName BusinessRegistrationNumber	境外/离岸主体注册信息：注册状态、管辖区、税号、成立日期、标准化登记号。两者至少传一个，建议优先传登记号；BusinessName 只认中文工商全名
parse_address	address	地址解析：把自由文本拆成省/市/区/街道/道路/门牌/楼层/房间/邮编/POI，并返回 errorcontent 说明地址异常原因

5推荐调用顺序

先查全名：fuzzy_query_company(keyWord="腾讯")，从候选里挑出准确全名。
再查详情：把全名传给 query_company_basic_info(entname=...) 或其他工具。
需要多维度画像时，用同一个全名并行调用商标、专利、涉诉等工具。

两步调用的请求体

# 第一步：先用关键词模糊查询，拿到企业全名
{"jsonrpc":"2.0","id":10,"method":"tools/call",
 "params":{"name":"fuzzy_query_company","arguments":{"keyWord":"腾讯"}}}

# 第二步：用全名查详情（参数名是 entname，不是 entName）
{"jsonrpc":"2.0","id":11,"method":"tools/call",
 "params":{"name":"query_company_basic_info","arguments":{"entname":"深圳市腾讯计算机系统有限公司"}}}

用 Python 直接调的话，注意响应是 SSE，需要先切出 data: 行：

python

import json, requests

BASE = "https://mcp.usendata.com/mcp"
HEAD = {
    "Authorization": "Bearer <TOKEN>",
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
}

s = requests.Session()
s.headers.update(HEAD)
r = s.post(BASE, json={"jsonrpc": "2.0", "id": 1, "method": "initialize",
                       "params": {"protocolVersion": "2025-06-18",
                                  "capabilities": {},
                                  "clientInfo": {"name": "py", "version": "1.0"}}})
s.headers["mcp-session-id"] = r.headers["mcp-session-id"]

r = s.post(BASE, json={"jsonrpc": "2.0", "id": 2, "method": "tools/call",
                       "params": {"name": "query_company_basic_info",
                                  "arguments": {"entname": "深圳市腾讯计算机系统有限公司"}}})

# 响应是 SSE：正文形如 "event: message\ndata: {...}"
data = [l[6:] for l in r.text.splitlines() if l.startswith("data: ")]
print(json.loads(data[-1])["result"]["content"][0]["text"])

6错误排查

先看 HTTP 状态码，再看响应体。下表的前四行覆盖了绝大多数接入问题。

状态码	响应	原因	处理
401	{"error":"unauthorized"}	没带 token、token 写错、已停用或已过期	到「Token 管理」确认该 token 状态与过期时间；不确定就重新生成一个
406	Not Acceptable	Accept 头缺 text/event-stream	补齐为 application/json, text/event-stream
400	Bad Request	没先 initialize 就来调 tools/list，或缺少 mcp-session-id	按「手动调用」三段流程先初始化并带上 session 头
404	"Session not found"	会话已失效（服务重启、长时间空闲、客户端复用了旧 session）	重新 initialize；客户端一般会自动重连，重连后仍失败就看客户端日志
200	isError:true "Unknown tool: xxx"	工具名拼错，或客户端缓存了旧工具列表	对照第 4 节清单；重启客户端刷新工具列表
200	isError:true "Field required"	参数名写错或大小写不符	照抄第 4 节的参数名
421	Misdirected Request	请求的 Host 头不在服务端白名单里（常见于用 IP 直连或自建反代）	改用 mcp.usendata.com 域名访问；确需新增域名请联系管理员
其它	返回业务错误信息	上游羽山接口报错：额度不足、无该产品权限、参数不符合要求	把返回里的 message 和流水号（如 20261103154744244ABZX）一并反馈

小技巧：401 不要先怀疑网络或证书。证书问题浏览器会直接报 TLS 错误；能返回 401 说明网络是通的，问题一定在 token 上。

7Token 管理

新建：在「Token 管理」填用途名称和有效期（留空为永久）。明文只显示一次，关掉页面就再也看不到。
重新生成：换一个新的 token，旧的立即失效。适合怀疑泄漏、或需要定期轮换时用。记得同步更新所有客户端。
停用 / 启用：临时封禁但保留记录。停用后请求立刻返回 401，启用后原 token 继续可用，不用改客户端。
删除：不可恢复，列表里的记录一并消失。
漏了 token 怎么办：库里只存 sha256，找不回来。点「重新生成」拿新的，旧的自动作废。

发放建议：一个客户端一个 token，按「人 + 环境」分开发放（例如张三-笔记本、生产服务器）。这样某处泄漏只吊销那一个，不影响其他人；列表里的「最后使用」还能帮你识别哪个 token 已经没人用了。

8安全建议

token 等同于账号密码，不要写进前端代码、公开仓库、聊天记录；配置文件里用环境变量占位。
只走 HTTPS，不要用 http:// 明文传 token。
建议 90 天轮换一次；人员离职或设备丢失立即停用对应 token。
登录密码与羽山 api_key 是两套东西：前者只保护后台页面，后者决定能查什么数据。发现后台账号异常，先改密码再看 token 列表。

文档版本 v1.0 · 更新于 2026-11-03

接入文档 Streamable HTTP · MCP 打印 / 存为 PDF

1接入信息

2客户端配置

WorkBuddy

Claude Code

Cursor、Cline、Cherry Studio 等通用 JSON 客户端

VS Code（GitHub Copilot MCP）

Claude Desktop 等只支持本地 stdio 的客户端

3手动调用（curl 全流程）

4工具清单

5推荐调用顺序

6错误排查

7Token 管理

8安全建议

接入文档 Streamable HTTP · MCP