diff --git a/docs/E2E_FREE_MCP_INFERENCE_CHECKLIST.md b/docs/E2E_FREE_MCP_INFERENCE_CHECKLIST.md new file mode 100644 index 0000000..0f4ed91 --- /dev/null +++ b/docs/E2E_FREE_MCP_INFERENCE_CHECKLIST.md @@ -0,0 +1,10 @@ +# E2E Checklist — agent-cli (Phase 4) + +See web-auth `docs/E2E_FREE_MCP_INFERENCE_CHECKLIST.md` for full stack flows. + +## agent-cli specific + +- [ ] MCP connect without subscription ID still uploads metering events +- [ ] `openrouter_chat` requires inference plan at gateway (not agent-cli local gate) +- [ ] Builder fee regression: `tests/test_builder_fee.py` unchanged pass +- [ ] Exhibit A harness documents free MCP vs inference paths (`docs/FREE_MCP_METERING.md`) diff --git a/docs/FREE_MCP_METERING.md b/docs/FREE_MCP_METERING.md new file mode 100644 index 0000000..542f323 --- /dev/null +++ b/docs/FREE_MCP_METERING.md @@ -0,0 +1,21 @@ +# Free MCP metering (no inference subscription) + +As of the 2026-07-07 product split, **MCP trading tools are free** and monetized via Hyperliquid builder code. An inference subscription is optional and only required for Nunchi/OpenRouter-backed `openrouter_chat`. + +## Gateway behavior + +- `mcp-gateway` calls web-auth `/api/metering/status` **only when**: + - the connect payload includes `subscription_id` (inference subscriber), or + - the tool is `openrouter_chat`. +- Free MCP tool calls (`trade`, `funding_hedge_execute`, market reads, etc.) proceed without subscription quota checks. + +## agent-cli expectations + +- `POST /api/mcp/connect` may omit `planId` / subscription fields for free MCP. +- When no inference subscription is active, web-auth mints gateway tokens with `plan_id: free-mcp` and no `subscription_id`. +- Usage upload (`POST /api/metering/usage`) still records control-plane and tool events for observability; it does not gate free MCP trading. +- BYO inference (user-supplied model keys) stays outside Nunchi metering unless the user purchases an inference plan. + +## When to pass subscription context + +Pass `subscription_id` and inference `plan_id` from web-auth connect only when the user has an active inference subscription. agent-cli should not fabricate subscription IDs for free MCP sessions.