Argosvix — AI agent observability (87 tools)

@argosvix/mcp-server

Argosvix MCP 服务让 AI Agent（Claude Desktop、Cursor、Codex CLI、自定义 MCP 客户端）可以直接在对话中查询、管理和操作 LLM 可观测性数据。支持 stdio（子进程）和 HTTP（远程 / 自托管）传输方式。

**功能范围：**89 个工具（86 个正式可用工具 + 3 个内部运维工具，客户账户调用时会返回 403）/ 3 个资源 / 8 个资源模板 / 3 个提示词。健康状况和异常检测端点（get_account_health / detect_anomaly / propose_alert_rules / classify_calls_batch / propose_eval_criteria）以及运行时控制平面（预算门控 / 策略门控 / 人工审批门控）让 Agent 能够同时进行观察和操作。发布历史可在 npm 查看。

为什么选择它

你已经在通过 @argosvix/sdk 或 Python SDK 发送 LLM 调用。现在可以向 Claude / Cursor 提出这样的问题：

• “过去 24 小时我的 OpenAI 费用是多少？”
• “现在有哪些告警正在触发？”
• “列出今天费用最高的 20 次调用。”

无需在仪表盘标签页之间切换。Agent 会通过此 MCP 服务，使用你的 Argosvix API 密钥获取数据。

安装

一键安装（启动时无需密钥；之后设置 ARGOSVIX_API_KEY 即可使用工具访问自己的账户）：

Claude Code 用户也可以改为安装 argosvix plugin，其中包含此服务和设置技能：

/plugin marketplace add argosvix/claude-plugin
/plugin install argosvix@argosvix
/reload-plugins

手动安装：

npm install -g @argosvix/mcp-server

配置（Claude Desktop）

编辑 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_..."
      }
    }
  }
}

重启 Claude Desktop。全部 89 个工具都会以 argosvix__ 为前缀显示（例如 argosvix__query_calls、argosvix__get_account_health、argosvix__create_budget_gate）。

还没有 API 密钥？ 即使未设置 ARGOSVIX_API_KEY，服务也会以仅供检查的模式启动：89 个工具都会列出，方便你了解功能范围；两个公开数据工具（get_synth_daily / get_daily_readthrough——Argosvix 自己的每日 AI 摘要和 OSS 阅读数据）完全无需密钥即可使用。调用其他所有工具时，都会返回获取密钥的说明：https://dashboard.argosvix.com/api-keys。

关于公开数据工具的说明：它们仅包含在默认的 full 配置中（不包含在 ARGOSVIX_MCP_PROFILE=core 中），并且与其他工具一样遵循 ARGOSVIX_API_BASE 的设置——如果将服务指向其他基础 URL，它们会在不进行身份验证的情况下，从该地址获取 /v1/synth-daily / /v1/readthrough。

配置（Cursor）

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_..."
      }
    }
  }
}

工具配置（ARGOSVIX_MCP_PROFILE）

默认配置为 full（包含全部 89 个工具）。如果 MCP 客户端的上下文预算有限，可设置 ARGOSVIX_MCP_PROFILE=core，仅启用日常操作所需的 11 个核心工具：

query_calls · aggregate_calls · get_cost_summary · get_percentiles · get_account_health · detect_anomaly · list_alerts · create_alert · silence_alert · unsilence_alert · get_deployed_prompt

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_...",
        "ARGOSVIX_MCP_PROFILE": "core"
      }
    }
  }
}

stdio 和 HTTP 传输方式均适用。对于未知值，系统会回退到 full，并在 stderr 输出警告。

描述语言（ARGOSVIX_MCP_LANG）

tools/list / resources/list / prompts/list 返回的工具、资源和提示词描述默认使用英语。设置 ARGOSVIX_MCP_LANG=ja 可获取日语原文描述。未设置或值未知时，将回退到 en（值未知时会在 stderr 输出警告）。两种语言下的工具名称、输入架构和行为完全相同，只有面向用户 / Agent 的描述文本会变化。

{
  "mcpServers": {
    "argosvix": {
      "command": "argosvix-mcp",
      "env": {
        "ARGOSVIX_API_KEY": "argk_...",
        "ARGOSVIX_MCP_LANG": "ja"
      }
    }
  }
}

适用于 stdio 和 HTTP 传输。

工具（概览）

共有 89 个工具，完整列表由 tools/list 返回。以下是核心读写功能示例：

工具	用途	类型
query_calls	最近的大模型调用记录，可按提供商 / 模型 / 时间范围筛选	读取
get_cost_summary	按提供商或模型汇总成本 / 调用次数 / 令牌数	读取
list_alerts	已配置的告警 + 最近触发状态	读取
get_alert	特定告警详情 + 最近触发历史	读取
list_alert_events	账户内的告警触发事件（通知历史）	读取
silence_alert	静音特定告警（= 暂停通知，默认 24h）	写入
unsilence_alert	恢复之前已静音告警的通知	写入
create_alert	创建新的告警规则（成本 / 错误率 / 延迟 / 异常）	写入
acknowledge_alert	将特定告警事件标记为已确认（幂等，与静音相互独立）	写入

资源

资源提供只读快照，AI Agent 无需显式调用工具即可将其载入上下文。

URI	用途
argosvix://account	套餐 / 配额 / 本月当前记录用量 / 保留期限快照（非敏感，仅限 Bearer）
argosvix://alerts/active	当前已启用告警的快照
argosvix://cost/today	过去 24 小时按提供商划分的成本明细（含 response.total）

资源模板

资源模板允许 Agent 根据已知 ID 构造动态 URI。服务会在后端通过主键查询强制限定账户范围，因此跨账户 ID 会返回 404。

URI 模板	用途
argosvix://calls/{id}	单条大模型调用记录（提供商 / 模型 / 令牌数 / 成本 / 延迟 / 标签 / 错误 / trace_id）。填入 query_calls 结果中的任意 ID。
argosvix://alerts/{id}	单条告警规则（名称 / 类型 / 阈值 / 窗口 / channelKinds / 睡眠 / 启用状态 / silencedUntil）+ 最近 20 条触发事件。填入 list_alerts 结果中的任意 ID。channelTargets（通知目标）会在结构上被剔除。
argosvix://traces/{id}	单条追踪记录 = 按 trace_id 分组的所有跨度（大模型调用时间序列）。仅包含前 50 个跨度（大模型上下文预算上限）；errorDetails / requestMeta 会在结构上被剔除。填入 query_calls 结果中的任意 traceId。

提示词

提示词是可复用模板，用户可以通过斜杠命令启动。

名称	用途
cost_review	比较 24h / 7d / 30d 的成本趋势并标记异常
alert_audit	审核当前告警规则并提出改进建议
incident_triage	调查近期的错误 / 延迟异常（默认最近 24h）

订阅（= v0.10，仅支持 stdio）

stdio 模式下会声明 resources.subscribe 能力。客户端可以订阅以下一个或多个静态资源；服务端每 60 秒轮询每个已订阅资源，并在内容哈希发生变化时发出 notifications/resources/updated。

可订阅的 URI（资源模板，例如 argosvix://calls/{id}，不可订阅）：

• argosvix://account
• argosvix://alerts/active
• argosvix://cost/today

HTTP 传输（= argosvix-mcp --http）不会声明 subscribe，并会拒绝订阅请求，因为每个请求无状态的模式无法保留订阅集合或发送由服务端发起的通知。实时更新请使用 stdio。

我们有意不声明 listChanged：资源列表在服务运行期间固定不变。

实现说明（v0.10）：

• 单飞保护：缓慢的轮询周期不会与下一个周期并发运行（= 不会重叠调用 readResource）。
• 取消订阅／关闭竞态：在获取前和通知前按 URI 重新检查，并使用 isShuttingDown 标志，因此不会为周期中途移除的 URI 发出通知。
• 故障处理：获取和通知失败时不输出信息（下一个周期会重试）。设置 ARGOSVIX_MCP_DEBUG=1 后，服务端会向 stderr 记录 { uri, errorClass }——有意不记录错误消息，以免泄露上游负载文本。
• 测试：150 项单元测试（包括重叠单飞＋取消订阅／关闭竞态＋无效 URI → McpError(InvalidParams)＋axis 4 Tier 1 dispatcher 覆盖）。

隐私

MCP 服务会使用你的 API 密钥向 https://ingest.argosvix.com 发送查询。不会暴露任何提示词或补全内容——仅发送元数据（令牌、费用、延迟、模型名称、你的标签）。

开发

npm install
npm run build
npm test

许可证

MIT © Yuto Makihara (Argosvix)。参见 LICENSE。

HTTP 传输

服务端也可以通过 HTTP 作为远程 MCP 端点运行，适用于可自托管或多租户场景，此类场景会在每个请求中提供 API 密钥。

# Start HTTP transport (default: 127.0.0.1:3000)
argosvix-mcp --http

# Bind to all interfaces with custom port + allowed Host headers
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_PORT=4000 \
MCP_HTTP_ALLOWED_HOSTS="mcp.example.com,localhost:4000" \
  argosvix-mcp --http

端点

• GET /health → 返回包含服务名称／版本的 200 OK（无需身份验证）
• POST /mcp → MCP JSON-RPC 端点（需要身份验证）

客户端示例

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer argk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

身份验证模式

每个请求都必须包含 Authorization: Bearer <api-key>，并使用有效的 Argosvix API 密钥（在 https://dashboard.argosvix.com/api-keys 申请）。服务端使用无状态模式（无会话 ID），因此每个请求彼此独立，并且可以携带不同的密钥。

安全说明

• 默认绑定地址为 127.0.0.1（仅限 localhost）。如需对外开放，请使用 MCP_HTTP_HOST=0.0.0.0，但在生产环境中务必搭配反向代理＋TLS。
• localhost 绑定会启用 DNS 重绑定防护，通过将 Host 标头与已知的 localhost 允许列表进行比对来实现。非本地绑定时，请使用 MCP_HTTP_ALLOWED_HOSTS（逗号分隔）。
• 请求正文大小上限为 1 MiB。

调试日志

默认情况下不会记录后端错误响应正文，以免生产环境的日志聚合器收集到后端内部负载。若要在调试期间启用原始正文日志：

ARGOSVIX_MCP_DEBUG=1 argosvix-mcp           # stdio mode
ARGOSVIX_MCP_DEBUG=1 argosvix-mcp --http    # HTTP mode

未设置环境变量时，错误日志仅包含 path、status 和 x-request-id。