@argosvix/mcp-server

v0.30.0-alpha.10 — Argosvix MCP server lets AI agents (Claude Desktop, Cursor, Codex CLI, custom MCP clients) query, manage, and operate their LLM observability data directly from the conversation. Supports both stdio (subprocess) and HTTP (remote / self-host) transports.

Surface: 87 tools (84 generally available + 3 founder-ops scoped) / 3 resources / 8 resource templates / 3 prompts. Autonomous-AI-ops endpoints (get_account_health / detect_anomaly / propose_alert_rules / classify_calls_batch / propose_eval_criteria) plus runtime control plane (budget gates / policy gates / human-approval gates) complete the "agent that can both observe AND act" narrative. Release history is available on npm.

Why

You're already sending LLM calls through @argosvix/sdk or the Python SDK. Now ask Claude / Cursor questions like:

- "What was my OpenAI cost over the past 24h?"
- "Which alerts are firing right now?"
- "Show me the 20 most expensive calls today."

No dashboard tab-switching. The agent fetches the data via this MCP server using your Argosvix API key.

Install

npm install -g @argosvix/mcp-server

Configure (Claude Desktop)

Edit your Claude Desktop config:

- 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_..."
      }
    }
  }
}

Restart Claude Desktop. All 87 tools appear under the argosvix__ prefix (e.g. argosvix__query_calls, argosvix__get_account_health, argosvix__create_budget_gate).

> No API key yet? The server also starts without ARGOSVIX_API_KEY in introspection-only mode (since v0.30.0-alpha.14): all 87 tools are listed so you can evaluate the surface, and any tool call returns instructions for getting a key at https://dashboard.argosvix.com/api-keys.

Configure (Cursor)

Edit ~/.cursor/mcp.json:

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

Tool profile (ARGOSVIX_MCP_PROFILE)

The default profile is full (all 87 tools). If your MCP client's context budget is tight, set ARGOSVIX_MCP_PROFILE=core to expose only the 11 essentials for day-to-day operations:

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"
      }
    }
  }
}

Works in both stdio and HTTP transports. Unknown values fall back to full with a warning on stderr.

Description language (ARGOSVIX_MCP_LANG)

Tool, resource, and prompt descriptions returned by tools/list / resources/list /
prompts/list are in English by default. Set ARGOSVIX_MCP_LANG=ja to get the original
Japanese descriptions instead. Unset or unknown values fall back to en (with a warning
on stderr for unknown values). Tool names, input schemas, and behavior are identical in
both languages — only the human/agent-facing description text changes.

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

Works in both stdio and HTTP transports.

Tools (highlights)

87 tools in total — the full list is returned by tools/list. A sample of the core read / write surface:

| Tool | Purpose | Type |
|---|---|---|
| query_calls | Recent LLM call records, filterable by provider / model / time range | read |
| get_cost_summary | Aggregate cost / calls / tokens by provider or model | read |
| list_alerts | Configured alerts + recent trigger status | read |
| get_alert | Detail of a specific alert + recent trigger history | read |
| list_alert_events | Alert trigger events across the account (notification history) | read |
| silence_alert | Mute a specific alert (= temporary notification stop, default 24h) | write |
| unsilence_alert | Resume notifications for a previously muted alert | write |
| create_alert | Create a new alert rule (cost / error rate / latency / anomaly) | write |
| acknowledge_alert | Mark a specific alert event as acknowledged (idempotent, orthogonal to silence) | write |

Resources (Phase 3, expanded in 0.5.0-alpha.1)

Resources expose read-only snapshots that AI agents can pull into context without an explicit tool call.

| URI | Purpose |
|---|---|
| argosvix://account | Plan / quota / current-month record usage / retention snapshot (non-sensitive, Bearer-only) |
| argosvix://alerts/active | Snapshot of currently enabled alerts |
| argosvix://cost/today | Last-24h cost breakdown by provider (with response.total) |

Resource templates (Phase 3, expanded in 0.8.0-alpha.1)

Resource templates let agents construct dynamic URIs from a known id. The server enforces account scope via PK lookup on the backend, so cross-account ids return 404.

| URI template | Purpose |
|---|---|
| argosvix://calls/{id} | Single LLM call record (provider / model / tokens / cost / latency / tags / error / trace_id). Plug in any id from query_calls results. |
| argosvix://alerts/{id} | Single alert rule (name / type / threshold / window / channelKinds / sleep / enabled / silencedUntil) + recent 20 trigger events. Plug in any id from list_alerts results. channelTargets (notification destinations) is structurally dropped. |
| argosvix://traces/{id} | Single trace = all spans grouped by trace_id (LLM call time-series). Top 50 spans only (LLM context budget cap); errorDetails / requestMeta are structurally dropped. Plug in any traceId from query_calls results. |

Prompts (Phase 3, new in 0.4.0-alpha.1)

Prompts are reusable templates the user can launch as slash commands.

| Name | Purpose |
|---|---|
| cost_review | Compare 24h / 7d / 30d cost trends and flag anomalies |
| alert_audit | Audit current alert rules and propose improvements |
| incident_triage | Investigate recent error / latency anomalies (default last 24h) |

Subscriptions (= v0.10, stdio only)

resources.subscribe capability is declared in stdio mode. Clients can subscribe to one or more of the static resources below; the server polls each subscribed resource every 60 seconds and emits notifications/resources/updated when the content hash changes.

Subscribable URIs (resource templates such as argosvix://calls/{id} are not subscribable):

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

HTTP transport (= argosvix-mcp --http) does not declare subscribe and rejects subscribe requests, since per-request stateless mode cannot keep a subscription set or deliver server-initiated notifications. Use stdio for live updates.

listChanged is intentionally not declared: the resource list is fixed for the server lifetime.

Implementation notes (v0.10):
- Single-flight guard: a slow polling cycle does not start a concurrent next cycle (= no overlapping readResource calls).
- Unsubscribe / shutdown race: per-URI re-check before fetch and before notify, plus an isShuttingDown flag, so notifications are not emitted for URIs removed mid-cycle.
- Failure handling: fetch and notify failures are silent (next cycle retries). With ARGOSVIX_MCP_DEBUG=1 the server logs { uri, errorClass } to stderr — error messages are intentionally not logged to avoid leaking upstream payload text.
- Tests: 150 unit tests (incl. overlap single-flight + unsubscribe / shutdown race + invalid URI → McpError(InvalidParams) + axis 4 Tier 1 dispatcher coverage).

Privacy

The MCP server sends queries to https://ingest.argosvix.com using your API key. No prompts or completions are exposed — only metadata (tokens, cost, latency, model name, your tags).

Development

npm install
npm run build
npm test

License

MIT © Yuto Makihara (Argosvix). See LICENSE.

HTTP transport (new in 0.3.0-alpha.1)

The server can also run as a remote MCP endpoint over HTTP, suitable for
self-hosting or multi-tenant scenarios where API key is supplied per request.

```bash