MCP Server

把 Argus 里你项目的可观测数据，通过**模型上下文协议（MCP）**暴露给 AI——在 Claude / Cursor / ChatGPT 等任意支持 MCP 的终端里，用自然语言查询日志、崩溃、性能、埋点、漏斗 / 留存、Trace、反馈、实验与配置数据。这是 Argus MCP-First 战略的对外接入轨；Console 内嵌的 Platform Copilot 复用同一套工具集。

对应服务：services/mcp-server · 可运行示例：examples/mcp-quickstart · 产品定义：docs/02-product/30-mcp-server.md

它是只读的、按项目隔离的

只读：所有工具都是查询，不写入、不执行任何操作。会改变状态的操作（如触发日志回捞的 log.recall_trigger）物理不注册进工具清单——AI 对回捞只能「看」（列文件 / 读条目 / 读审计），不能「做」。
按项目绑定：鉴权用的个人访问令牌（PAT）绑定到一个 project，服务端把该 project_id 强制注入每次工具调用——调用方不需要、也无法传 project_id，只能查自己项目的数据。
需要 mcp:read scope：PAT 必须含此 scope，且已绑定项目（fail-closed，任一条件缺失即 401）。

接入步骤

创建 MCP 凭证（PAT）

在 Argus Console 左上角选好项目后，打开 Copilot / MCP 页（路径 /mcp）：

填写凭证名称（如 my-laptop-claude）与有效期（默认 90 天），点击生成。创建属于高敏操作，会要求 step-up 二次验证。
生成的 token 形如 argus_pat_xxxxxxxx，只显示一次，立即保存。
该凭证自动带 mcp:read scope，并绑定到当前项目——一个 token 只能查一个项目。

不再使用时可在同一页吊销，连接立即失效。PAT 的通用说明（Settings 里的 Personal Access Tokens 页签发的是 read scope 的 API 凭证，不能用于 MCP）见账号与认证。

确认 MCP Server 地址

Argus Cloud：https://mcp.argusplatform.com（占位，以 Console 页面显示的 Endpoint 为准）
本地起栈 / 自托管：http://localhost:8092

MCP 端点是地址后的 /mcp 路径，鉴权方式为 Authorization: Bearer argus_pat_xxx 请求头。

配置你的 AI 客户端

见下方客户端配置，三种主流客户端任选。

验证

Claude Code：输入 /mcp，应看到 argus 已连接并列出工具。
Cursor：Settings 中的 MCP 页应显示 argus 绿点（connected）。
任意客户端：直接问一句「查一下最近 10 条 ERROR 日志」，AI 应调用 log.recent。

客户端配置

Claude Code

在项目根创建 .mcp.json（Console 的 Copilot / MCP 页会生成填好 token 的同款片段）：


{
  "mcpServers": {
    "argus": {
      "type": "http",
      "url": "http://localhost:8092/mcp",
      "headers": { "Authorization": "Bearer argus_pat_xxxxxxxx" }
    }
  }
}

把 url 换成你的 MCP Server 地址（Cloud 用户换成 Console 显示的 Endpoint）。配置只在启动时读取一次：/quit 退出后重新运行 claude，首次会询问是否信任该 server，确认即可。用 /mcp 查看连接状态与工具清单。

建议把含真实 token 的 .mcp.json 加进 .gitignore，避免凭证入库。

Claude Desktop

Claude Desktop 通过 mcp-remote 代理连接「带鉴权头的远程 HTTP MCP server」。编辑 claude_desktop_config.json （Settings → Developer → Edit Config）：


{
  "mcpServers": {
    "argus": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.argusplatform.com/mcp",
        "--header",
        "Authorization: Bearer argus_pat_xxxxxxxx"
      ]
    }
  }
}

配置文件位置：

平台	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

改完必须完全退出（菜单栏 Quit，不是关窗口）再重新打开。对话窗口的连接图标里应看到 argus 已连接。

Cursor

Cursor 支持直连带鉴权头的 HTTP MCP。写进 ~/.cursor/mcp.json（用户级，全部项目可见）或项目根 .cursor/mcp.json（项目级）：


{
  "mcpServers": {
    "argus": {
      "url": "http://localhost:8092/mcp",
      "headers": { "Authorization": "Bearer argus_pat_xxxxxxxx" }
    }
  }
}

完全退出 Cursor 重新打开，在 Settings 的 MCP 页确认 argus 显示绿点并列出工具。

ChatGPT：在 Settings → Connectors 添加自定义 MCP，URL 填 MCP 端点（如 http://localhost:8092/mcp），Authorization 头填 Bearer argus_pat_xxx。

连上后直接问，例如：

「昨天哪个崩溃 issue 影响用户最多？」→ AI 调 crash.aggregate
「近 7 天冷启动的 p95 是多少？在变慢吗？」→ apm.stats
「用户最近反馈了什么问题？」→ feedback.search
「注册 → 激活 → 购买的漏斗在哪一步掉得最多？iOS vs Android？」→ analytics.funnel
「这条 trace 慢在哪一跳？」→ trace.get
「v2.3 和 v2.2 哪个版本更健康？」→ release.health

不走 MCP 客户端：直接 REST 调用

同一套工具也暴露为 REST：POST /v1/tools/{name}，body 是该工具入参 JSON（同样不含 project_id）。适合脚本、OpenAI function-calling、任意 HTTP 客户端：


export ARGUS_MCP_URL=https://mcp.argusplatform.com
export ARGUS_MCP_TOKEN=argus_pat_xxxxxxxx
 
curl -X POST "$ARGUS_MCP_URL/v1/tools/apm.stats" \
  -H "Authorization: Bearer $ARGUS_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"days":7}'

全部工具的入参 / 返回 schema 可公开发现（无需鉴权）：


curl "$ARGUS_MCP_URL/openapi.json"

更多 REST 细节见 OpenAPI / REST。可运行的零依赖脚本示例见 examples/mcp-quickstart/query.sh。

两种 transport

transport	启动	端点	鉴权	用途
HTTP（StreamableHTTP + REST）	`npm run start:http`，监听 `:8092`	`POST/GET /mcp`、`POST /v1/tools/{name}`、`GET /openapi.json`、`GET /healthz`	Bearer PAT	托管 / 多人接入（推荐）
stdio	`npm start`（bin `argus-mcp`）	标准输入输出	无（直连内部服务）	本地起栈 / 自托管内网，由 AI 客户端直接 spawn 进程

两者的差异要留意：HTTP 模式下 PAT 决定项目，工具 schema 中没有 project_id 字段； stdio 模式没有 PAT 鉴权，工具入参需要显式传 project_id，它通过环境变量直连后端服务，只应在可信的本机 / 内网环境使用。

stdio / 服务端环境变量：

变量	默认	说明
`ARGUS_MCP_HTTP_PORT`	`8092`	HTTP transport 端口
`ARGUS_OBSERVABILITY_ENDPOINT`	`http://localhost:8080`	observability-core 地址
`ARGUS_IDENTITY_INTERNAL_URL`	`http://localhost:8081`	identity（PAT 校验）地址
`ARGUS_RECALL_ENDPOINT`	`http://localhost:8087`	recall 服务地址（启用日志回捞只读工具）
`ARGUS_CONFIG_ENDPOINT`	`http://localhost:8083`	config 服务地址（启用 `config.get` / `experiment.list`）
`ARGUS_COPILOT_ENDPOINT`	`http://localhost:8093`	copilot 服务地址（启用 `verify.*` 工具）
`ARGUS_INTERNAL_SECRET`	—	service-to-service 内部密钥

工具全量参考

以下清单与 services/mcp-server/src/tools/ 源码注册处逐一核对，共 39 个工具定义：

普通项目 PAT 经 HTTP 接入、全量服务部署时可见 38 个；
admin.visibility.list 仅持 mcp:admin scope 的运营 token 可见；
stdio 入口不接 config 服务，为 36 个（不含 config.get / experiment.list / admin.visibility.list）；
log.list_files 等回捞工具在 recall 服务未部署时不注册，verify.* 在 copilot 服务未部署时不注册。

下表「关键参数」省略 project_id（HTTP 模式由 token 绑定自动注入；stdio 模式需显式传入）。 limit 均为可选，括号内是默认值。

日志（5）

工具	用途	关键参数
`log.search`	按消息子串全文搜索日志（大小写不敏感的字面匹配，非倒排索引）	`search`（必填）、`source`（backend/device）、`trace_id`、`event_id`、`limit`（20）
`log.recent`	最近 N 条日志，可按级别 / 来源 / trace 过滤	`level`（DEBUG..FATAL）、`source`、`trace_id`、`limit`（20）
`log.by_user`	某个最终用户的日志，重建其经历	`user_id`（必填）、`limit`（50）
`log.by_session`	单个会话内的全部日志（如崩溃前的时序）	`session_id`（必填）、`limit`（100）
`log.aggregate`	按维度聚合最近日志计数	`group_by`（level/user_id/platform，必填）、`limit`（500）

日志回捞（3，需部署 recall 服务）

工具	用途	关键参数
`log.list_files`	列出已上传（回捞）的端上加密日志文件	`device_id`、`user_id`、`date`（YYYY-MM-DD）、`q`（文件名模糊）、`limit`（50）
`log.file_entries`	读取某回捞文件解码后的日志条目（服务端解密 + 解压 + 解析）	`file_id`（必填）、`level`、`q`、`limit`（500）
`log.audit`	回捞审计轨迹：谁在何时下载 / 查看 / 触发了回捞	`limit`（100）

触发回捞的 log.recall_trigger 是会改变端上状态的写操作，不注册进 AI 工具清单，只能由人在 Console 上发起，见日志回捞。

崩溃（7）

工具	用途	关键参数
`crash.recent`	最近 N 条崩溃（含 breadcrumbs 解析）	`limit`（20）
`crash.get`	按 event_id 取单条崩溃详情	`event_id`（必填）
`crash.by_signature`	某个 issue（签名分组）下的全部崩溃事件	`signature`（16 位 hex，必填）、`limit`（50）
`crash.recurrence`	确定性判断某签名在指定时间后是否复发（验证修复是否生效）	`signature`（必填）、`since`（ISO 8601，必填）
`crash.by_user`	某用户的全部崩溃	`user_id`（必填）、`limit`（50）
`crash.aggregate`	按维度聚合崩溃计数（最热 issue / 最差平台 / 回归版本）	`group_by`（signature/error_type/device_os/app_version/user_id，必填）、`limit`（500）
`crash.stats`	近 N 天崩溃总量 + 签名分布 + 逐日趋势	`days`（14）、`app_version`

符号（2）

工具	用途	关键参数
`symbol.list`	列出项目已上传的符号 / 调试文件（iOS dSYM、Android .so、Web sourcemap）	`platform`（ios/android/web）
`crash.symbolicate`	手动（重新）触发某崩溃事件的符号化（异步，完成后用 `crash.get` 重取）	`event_id`（必填）

性能（APM，3）

工具	用途	关键参数
`apm.stats`	近 N 天性能指标聚合：每个 metric 的 count / avg / p50 / p95 / p99 / min / max	`days`（14）
`apm.search`	逐条查看原始性能样本（如最慢的启动样本）	`name`（精确 metric 名）、`search`、`limit`（20）
`apm.memory_growth`	内存增长最陡的会话 Top-N（疑似内存泄漏，线性回归斜率）	`days`（14）、`limit`（20）

Trace（3）

工具	用途	关键参数
`trace.search`	按 trace 聚合列出最近链路（根操作 / 总时长 / span 数 / 是否出错）	`user_id`、`session_id`、`status`（error/ok）、`operation`、`min_duration_ms`、`limit`（50）
`trace.get`	取单条 trace 的完整 span 树（瀑布图数据）	`trace_id`（必填）
`trace.aggregate`	按操作聚合：count、P50/P99 延迟、错误率（已按采样权重还原）	`days`、`limit`（100）

埋点（2）

工具	用途	关键参数
`track.recent`	最近的行为埋点原始事件（event_name / properties / 平台 / 版本）	`name`（精确事件名）、`user_id`、`search`、`limit`（20）
`track.stats`	近 N 天埋点总量、Top 事件、逐日趋势	`days`（14）

埋点分析（4）

工具	用途	关键参数
`analytics.funnel`	有序漏斗：逐步转化率，找流失点	`steps`（2-10 个事件名，必填）、`days`（14）、`window_hours`（24）、`platform`、`app_version`、`utm_source` / `utm_medium` / `utm_campaign`
`analytics.retention`	留存曲线：day-0 队列 d 天后仍活跃的比例	`days`（30）、`max_day`（7）、`platform`、`app_version`、`utm_*`
`analytics.cohorts`	分群留存矩阵：按首活队列拆开的留存对比	`days`（30）、`max_day`（7）、`granularity`（day/week/month）、`platform`、`app_version`、`utm_*`
`analytics.dimensions`	发现各过滤维度的实际取值（platform / app_version / utm_*）	`days`（30）

反馈（1）

工具	用途	关键参数
`feedback.search`	检索用户反馈（总结主题 / 拉某用户的反馈历史）	`user_id`、`search`、`limit`（20）

实验（2）

工具	用途	关键参数
`experiment.list`	列出项目定义的 A/B 实验（key / 状态 / 变体）	—
`experiment.results`	单个实验各变体的曝光 / 转化 / 显著性（含固定样本 z 检验与随时有效的序贯检验）	`experiment_key`（必填）、`days`（14）、`baseline`

版本（1）

工具	用途	关键参数
`release.health`	版本健康度 0-100 评分 + 等级（由无崩溃会话率 / ANR / 启动时长 / FPS 推导），支持多版本并排对比	`version` 或 `versions`（逗号分隔，二选一必填）、`days`（14）

用户 / 会话（2）

工具	用途	关键参数
`user.detail`	单用户 360 度视图：日志 + 崩溃 + 埋点 + 反馈一次取全	`user_id`（必填）、`limit`（每通道 10）
`session.detail`	单会话跨通道视图：该会话内的日志 / 崩溃 / 埋点 / 反馈	`session_id`（必填）、`limit`（50）

配置（1，需部署 config 服务）

工具	用途	关键参数
`config.get`	当前生效的远程配置：Feature Flag 求值结果、实验分配、活跃版本	`platform`、`app_version`（求值上下文）

Verify（2，需部署 copilot 服务）

工具	用途	关键参数
`verify.run`	对一个论断跑 AI 可信核验，返回带证据链的 verdict	`query`（必填）、`evidence_context`
`verify.run_session`	对一条或多条 trace 跑核验：自动拉 span 作证据再判定	`trace_id` 或 `trace_ids`、`expectation`、`doc_refs`、`code_scope`

详见 AI Verify。

运营（1，仅 `mcp:admin` token）

工具	用途	关键参数
`admin.visibility.list`	列出全部能力可见性（`vis_*`）flag 的受众配置（只读；`admin.visibility.update` 永不暴露给 AI）	—

限流、审计与安全

每次工具调用都会写审计（token / 用户 / 工具名 / 项目 / 状态），可在服务端追溯「AI 看了哪些数据」。
工具按组织的能力可见性（Feature Visibility）过滤：组织不可见的能力，其工具不出现在 tools/list 中。
凭证吊销立即生效；上报链路的 DSN / HMAC 与 MCP 无关，概念对照见 DSN 与 HMAC。

排错

现象	原因
`401 unauthorized`	token 缺失 / 失效 / 已吊销，或没绑定 project，或缺 `mcp:read` scope
`404 not_found`（REST）	工具名拼错——用 `GET /openapi.json` 看准确名字
查得到工具但结果为空（200）	该项目近 N 天确实没有此类数据（不是错误）
客户端显示 disconnected	配置改动后未完全重启客户端；或 MCP Server 地址 / 端口不对
某些工具没出现在清单里	对应后端服务未部署（recall / config / copilot），或该能力对你的组织不可见

常见问题

Q：一个 token 能查多个项目吗？

不能。PAT 与项目一一绑定，这是服务端强制的硬隔离。要查多个项目，就在各项目下分别创建凭证，在客户端里配成多个 MCP server（如 argus-app、argus-web）。

Q：怎么知道每个工具的完整入参和返回结构？

GET /openapi.json（公开、无需鉴权）返回全部工具的 OpenAPI schema。也可以先调 analytics.dimensions 之类的发现型工具，让 AI 弄清你项目里实际存在的过滤值再查。

Q：AI 返回的数据太多，把上下文撑爆了怎么办？

所有列表型工具都有 limit（默认 20-100）。让 AI 先用聚合类工具（crash.stats / apm.stats / log.aggregate）看全貌，再用明细工具下钻。

Q：MCP 工具能修改数据吗？比如让 AI 帮我关掉一个 Feature Flag？

不能。全部工具只读，写操作从工具清单层面物理隔离（见 AI 能力总览的安全红线）。AI 可以用 config.get 告诉你 flag 当前值，但修改必须由你在 Console 上完成。

Q：本地 make demo 起的栈怎么接？

MCP Server HTTP transport 在 http://localhost:8092，在 Console（http://localhost:3000）的 Copilot / MCP 页创建凭证后按上文配置即可；纯本机也可用 stdio 模式直接 spawn argus-mcp。