From 1245d73b6bb91dd637b782b21830e419eaaac79c Mon Sep 17 00:00:00 2001
From: MaheshtheDev <38828053+MaheshtheDev@users.noreply.github.com>
Date: Sat, 3 Oct 2026 00:02:10 +0000
Subject: [PATCH] fix(mcp): clear out-of-credits error and keep it out of error
 rate (#1753)

- 402 now tells the agent the org is out of credits and links to console.supermemory.ai/billing (the old message said "memory limit" and pointed at the retired app).

- PostHog MCP analytics tags these calls `$mcp_error_type: out_of_credits` with `$mcp_is_error: false`, so an empty balance no longer inflates the MCP error rate.
---
 apps/mcp/src/server/analytics.ts    | 10 ++++++++++
 apps/mcp/src/server/client/index.ts |  5 ++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/apps/mcp/src/server/analytics.ts b/apps/mcp/src/server/analytics.ts
index c2b30c0b..3c629926 100644
--- a/apps/mcp/src/server/analytics.ts
+++ b/apps/mcp/src/server/analytics.ts
@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/server"
 import { instrument, type MCPAnalyticsOptions } from "@posthog/mcp"
 import { PostHog } from "posthog-node"
+import { OUT_OF_CREDITS_MESSAGE } from "./client"
 import type { ActorContext, ServerEnv } from "./types"
 
 const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com"
@@ -68,6 +69,11 @@ const metadataOnlyMcpEvent: NonNullable<MCPAnalyticsOptions["beforeSend"]> = (
 		return null
 	}
 
+	const errorMessage = event.properties.$mcp_error_message
+	const outOfCredits =
+		typeof errorMessage === "string" &&
+		errorMessage.includes(OUT_OF_CREDITS_MESSAGE)
+
 	return {
 		...event,
 		properties: {
@@ -76,6 +82,10 @@ const metadataOnlyMcpEvent: NonNullable<MCPAnalyticsOptions["beforeSend"]> = (
 					(key) => event.properties[key] !== undefined,
 				).map((key) => [key, event.properties[key]]),
 			),
+			// Billing state, not a server bug, so keep it out of the error rate.
+			...(outOfCredits
+				? { $mcp_is_error: false, $mcp_error_type: "out_of_credits" }
+				: {}),
 			$process_person_profile: false,
 		},
 	}
diff --git a/apps/mcp/src/server/client/index.ts b/apps/mcp/src/server/client/index.ts
index a2ccc8e7..1b575e15 100644
--- a/apps/mcp/src/server/client/index.ts
+++ b/apps/mcp/src/server/client/index.ts
@@ -21,6 +21,9 @@ const MAX_CHARS = 200000
 export const DEFAULT_PROJECT_ID = "sm_project_default"
 const FETCH_TIMEOUT_MS = 30_000
 const MCP_SOURCE = "supermemory-mcp"
+// Analytics matches on this text to tag quota errors, keep them in sync.
+export const OUT_OF_CREDITS_MESSAGE =
+	"Out of credits. Top up or upgrade at https://console.supermemory.ai/billing"
 
 export type {
 	ContainerTag,
@@ -457,7 +460,7 @@ export class SupermemoryClient {
 				case 401:
 					throw new Error("Authentication failed. Please re-authenticate.")
 				case 402:
-					throw new Error("Memory limit reached. Upgrade at supermemory.ai")
+					throw new Error(OUT_OF_CREDITS_MESSAGE)
 				case 403:
 					throw new Error(
 						message ||