From 5604f168c17d3b05b0c47d9aa0f3ae5e0021ad57 Mon Sep 17 00:00:00 2001 From: JaeLeex Date: Wed, 8 Jul 2026 06:56:52 -0400 Subject: [PATCH 1/2] Document free MCP metering without inference subscription Clarify when agent-cli should omit subscription_id and how gateway quota enforcement applies only to inference subscribers. Co-authored-by: Cursor --- docs/FREE_MCP_METERING.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 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. From 475d74deb155b36ecfd45cd9ff4ff8f30e4a89b1 Mon Sep 17 00:00:00 2001 From: JaeLeex Date: Wed, 8 Jul 2026 07:16:02 -0400 Subject: [PATCH 2/2] Phase 4: add agent-cli E2E checklist for free MCP inference stack Cross-link web-auth Phase 4 checklist with agent-cli builder-fee and metering regression items. Co-authored-by: Cursor --- docs/E2E_FREE_MCP_INFERENCE_CHECKLIST.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/E2E_FREE_MCP_INFERENCE_CHECKLIST.md 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`)