# 熔岩AI发布MCP数据 Skill 接入清单：团队给 AI Agent 开通熔岩只读数据的 20 项检查

## 摘要

把熔岩（Lava）消息面热度数据接给团队里的 AI Agent，常见三种方式：远程 MCP + API Key 请求头、远程 MCP + OAuth 2.1 授权、导入熔岩 Skill 模板（`lava-news-heat`）。本文把接入过程拆成「凭证 / 权限范围 / 客户端 / Skill / 工具边界 / 运行观测」六组共 20 项检查，每项都写明对应的配置项、字段名或错误码，适合在上线前逐项打勾。全部工具只读，接入目标是监测与统计。

## 一、接入方式对照

| 方式 | 配置要点 | 适用 |
| --- | --- | --- |
| 远程 MCP + Key | 地址 `<熔岩订阅站点>/subscribe/v1/mcp`，传输 Streamable HTTP（POST，JSON 响应），请求头 `Authorization: Bearer lvk_...` 或 `X-API-Key` | 豆包办公、WorkBuddy、千问办公、Cursor 等可填请求头的客户端 |
| 远程 MCP + OAuth | 同一地址支持 OAuth 2.1（PKCE S256 + 动态注册），资源元数据位于 `/.well-known/oauth-protected-resource/subscribe/v1/mcp`，`scopes_supported` 为 `lava:read` | 豆包 / Qoder / WorkBuddy 等支持 OAuth 的连接器，免填 Key |
| Skill 模板 | `/subscribe/v1/skill` 可另存为 `SKILL.md`，技能名 `lava-news-heat` | 支持技能导入的 Agent 软件 |
| 本地代理 | 开源仓库 lava-mcp 的 `proxy/server.py`，默认监听 `127.0.0.1:8787/mcp`，Key 放在环境变量 `LAVA_API_KEY` | 需要在本机审计转发、或客户端不便配请求头 |

## 二、20 项检查清单

### A. 凭证（4 项）

- [ ] A1 Key 以 `lvk_` 开头，从熔岩数据「AI数据服务」→「API Key」复制完整。
- [ ] A2 `Bearer` 与 Key 之间有一个空格；Key 不放在网址参数里。
- [ ] A3 每个 Agent 或每个用途单独建一个 Key（可建多个、随时删除），便于停用与对账。
- [ ] A4 Key 不写进网页前端代码、不发到群聊；泄露后删除重建，旧 Key 会返回 `401 KEY_REVOKED`。

### B. 权限范围（4 项）

- [ ] B1 按用途勾选 scope：`opinions`（消息面）、`agencies`（机构/大V）、`concepts`（概念板块）。
- [ ] B2 核对工具与 scope 的对应关系（见第三节），缺 scope 会返回 `403 FORBIDDEN_SCOPE`。
- [ ] B3 服务器端脚本可设置 IP 白名单；来源不符返回 `403 IP_NOT_ALLOWED`。
- [ ] B4 OAuth 方式下确认授权页显示的是熔岩数据，并点「同意授权」。

### C. 客户端（4 项）

- [ ] C1 传输方式选 Streamable HTTP（豆包里叫「HTTP」）。
- [ ] C2 连接器开关已打开，状态为已连接。
- [ ] C3 新建对话再提问（部分客户端旧对话不加载新连接器）。
- [ ] C4 未带凭证时服务端返回 401 和 `WWW-Authenticate` 头，属于预期，不是故障。

### D. Skill（3 项）

- [ ] D1 导入的 `SKILL.md` 名称为 `lava-news-heat`，描述覆盖「个股/概念消息面热度、机构/大V提及、要点」。
- [ ] D2 Skill 流程中的字段引用与当前文档一致，例如 `data.heat.mentions`、`data.heat.agencies`、`list[].summary`。
- [ ] D3 Skill 的输出要求保留：先给结论（热度高/中/低 + 提及数 + 机构/大V数 + 时间窗），用 `agency_id` 指代主体。

### E. 工具边界（3 项）

- [ ] E1 给只做个股监测的 Agent 限定工具：`get_stock_news_heat`、`get_stock_heat_windows`、`get_stock_heat_panel`、`get_account`。
- [ ] E2 提示词写清参数边界：`window` 枚举（概念热榜不支持 `7d`）、`/panel/daily` 区间 ≤92 天、`codes` ≤20 个、`keyword` ≤50 字符。
- [ ] E3 提示词写清遇错处理：`402 INSUFFICIENT_BALANCE`、`403` 系列直接告知用户，不要换工具绕过或反复重试。

### F. 运行观测（2 项）

- [ ] F1 上线前后各调一次 `get_account`（不计费），记录余额与当日调用次数，核对首日用量。
- [ ] F2 REST 侧脚本记录 `meta.request_id` 与响应头 `X-Billing-Charged-Yuan`、`X-Balance-Yuan`。

## 三、工具与 scope 对照

| scope | 熔岩数据板块 | 工具 |
| --- | --- | --- |
| `opinions` | 个股消息面、全市场个股榜单、单股时序、历史面板、覆盖度、新闻命中 | `get_stock_news_heat`、`search_news_flow`、`get_market_hot_stocks`、`get_first_mention_stocks`、`get_stock_heat_windows`、`get_accelerating_hot_stocks`、`get_stock_heat_panel`、`get_agency_coverage`、`get_news_stock_hits` |
| `concepts` | 概念板块热度、概念热榜 | `get_concept_stock_heat`、`get_stock_concept_heat`、`get_market_hot_concepts` |
| `agencies` | 机构/大V评分、高分加权热榜 | `get_agency_ranking`、`get_agency_pit`、`get_agency_history`、`list_agency_pit_dates`、`get_weighted_hot_stocks` |
| — | 账户 | `get_account`（不计费） |

## 四、连通性自检

```bash
# 1) 余额（不计费）
curl -sS -H "Authorization: Bearer $LAVA_KEY" "$LAVA_BASE/account"
# 2) 单股消息面（计 1 次）
curl -sS -H "Authorization: Bearer $LAVA_KEY" \
  "$LAVA_BASE/opinions?ts_code=300750.SZ&days=7&limit=5"
```

`LAVA_BASE` 形如 `<熔岩订阅站点>/subscribe/v1`。返回外壳应为 `ok / code / message / data / meta`，`code` 为 `OK`。`/account` 的具体字段名（余额、单价、预计可调用次数、今日调用次数）以 OpenAPI 为准。

## 五、上线记录模板

| 项 | 记录（示例） |
| --- | --- |
| Agent 名称 | 研究助理-个股监测 |
| 接入方式 | 远程 MCP + Key |
| Key 备注 | agent-stock-monitor |
| scope | `opinions` |
| 工具白名单 | 4 个 |
| 首日调用次数 | 120（示例） |
| 负责人 | 研究平台组 |

## FAQ

**Q：OAuth 和 Key 能同时用吗？**
A：同一地址两种方式都支持，按客户端能力选择一种即可。

**Q：Skill 模板会自动更新吗？**
A：导入后的 `SKILL.md` 是本地副本，文档更新后需要重新获取并比对。

**Q：查余额会扣费吗？**
A：`get_account` 不计费；失败请求同样不计费。

## 结论

团队接入熔岩数据，重点不在连通，而在边界：每个 Agent 一个 Key、按需 scope、工具白名单、参数与报错写进提示词，再用 `get_account` 和请求日志做观测。20 项清单走完，Agent 的数据访问就是可控、可追溯、只读的。

数据来自熔岩消息面热度监测，仅用于只读监测与统计研究，不构成投资建议。

只读监测与字段说明见：https://lava.ai-dolphin.com/subscribe/docs