Skip to content

Context7 Platform -- Up-to-date docs for AI agents

CTX7-2472: Consume self-cancelling JSON-RPC batches (#3355)

Enes Gules7cbd5fd052cc
diff --git a/.changeset/mcp-reject-self-cancelling-batches.md b/.changeset/mcp-reject-self-cancelling-batches.md
new file mode 100644
index 00000000..721619bf
--- /dev/null
+++ b/.changeset/mcp-reject-self-cancelling-batches.md
@@ -0,0 +1,5 @@
+---
+"@upstash/context7-mcp": patch
+---
+
+Consume request/cancellation pairs contained in the same JSON-RPC batch before dispatch. This prevents the legacy stateless HTTP transport from leaving the response stream open when cancellation suppresses the terminal protocol response.
diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts
index 02a4fc19..27a39c4a 100644
--- a/packages/mcp/src/index.ts
+++ b/packages/mcp/src/index.ts
@@ -4,6 +4,7 @@ import { toNodeHandler } from "@modelcontextprotocol/node";
import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
import {
McpServer,
+ PROTOCOL_VERSION_META_KEY,
createMcpHandler,
type McpRequestContext,
type ServerContext,
@@ -36,6 +37,7 @@ import {
observeAuthentication,
observeUpstreamRequest,
recordAuthenticationEvent,
+ recordSelfCancellingBatch,
} from "./lib/telemetry-runtime.js";
import { mcpBodyErrorHandler } from "./lib/mcp-body-error-handler.js";
import {
@@ -159,6 +161,77 @@ const QUERY_DOCS_ALIASES: AliasMap = {
libraryId: ["context7CompatibleLibraryID", "libraryID", "libraryName"],
};
+type JsonRpcId = string | number;
+
+function jsonRpcRequestId(message: unknown): JsonRpcId | undefined {
+ if (!message || typeof message !== "object") return undefined;
+
+ const candidate = message as Record<string, unknown>;
+ if (
+ candidate.jsonrpc === "2.0" &&
+ typeof candidate.method === "string" &&
+ (typeof candidate.id === "string" || typeof candidate.id === "number")
+ ) {
+ return candidate.id;
+ }
+}
+
+function cancellationRequestId(message: unknown): JsonRpcId | undefined {
+ if (!message || typeof message !== "object") return undefined;
+
+ const candidate = message as Record<string, unknown>;
+ if (
+ candidate.jsonrpc !== "2.0" ||
+ candidate.method !== "notifications/cancelled" ||
+ "id" in candidate ||
+ !candidate.params ||
+ typeof candidate.params !== "object"
+ ) {
+ return undefined;
+ }
+
+ const requestId = (candidate.params as Record<string, unknown>).requestId;
+ if (typeof requestId === "string" || typeof requestId === "number") return requestId;
+}
+
+/** True for a 2026-07-28 message: its `params._meta` names a protocol version. */
+function hasProtocolVersionClaim(message: unknown): boolean {
+ if (!message || typeof message !== "object") return false;
+ const params = (message as Record<string, unknown>).params;
+ if (!params || typeof params !== "object") return false;
+ const meta = (params as Record<string, unknown>)._meta;
+ return !!meta && typeof meta === "object" && PROTOCOL_VERSION_META_KEY in meta;
+}
+
+function filterBatchSelfCancellations(body: unknown): {
+ body: unknown;
+ removedSelfCancellation: boolean;
+} {
+ if (!Array.isArray(body)) return { body, removedSelfCancellation: false };
+ // The SDK answers 400 to a batch with a 2026-07-28 element. Leave such a
+ // batch whole, so removing a pair cannot hide that element from the SDK.
+ if (body.some(hasProtocolVersionClaim)) return { body, removedSelfCancellation: false };
+
+ const requestIds = new Set(body.map(jsonRpcRequestId).filter((id) => id !== undefined));
+ const selfCancelledIds = new Set(
+ body
+ .map(cancellationRequestId)
+ .filter((id): id is JsonRpcId => id !== undefined && requestIds.has(id))
+ );
+ if (selfCancelledIds.size === 0) return { body, removedSelfCancellation: false };
+
+ return {
+ body: body.filter((message) => {
+ const requestId = jsonRpcRequestId(message);
+ if (requestId !== undefined && selfCancelledIds.has(requestId)) return false;
+
+ const cancelledId = cancellationRequestId(message);
+ return cancelledId === undefined || !selfCancelledIds.has(cancelledId);
+ }),
+ removedSelfCancellation: true,
+ };
+}
+
// z.preprocess step that rewrites aliased arg names before validation. Living
// in the schema keeps aliasing transport-agnostic: the SDK parses the wire
// message (any transport, any protocol era) and runs this on validation.
@@ -447,11 +520,10 @@ async function main() {
// millisecond vector query (p100 ~28s), so no legitimate exchange needs a
// heartbeat to stay alive — but a hung exchange kept "alive" by heartbeats
// can never be reaped by the gateway's stream idle timeout. A batch
- // carrying a request plus its own notifications/cancelled produces exactly
- // that: per spec the cancelled request gets no response, the SDK transport
- // then never closes the stream, and with heartbeats it survived until the
- // gateway's 1200s hard cap (the 2026-08-11 outage). Silent hangs instead
- // go idle and the gateway reaps them at streamIdleTimeout (300s).
+ // carrying a request plus its own notifications/cancelled produced exactly
+ // that (the 2026-08-11 outage); handleMcpRequest now consumes such pairs
+ // before dispatch. Any other silent hang goes idle and the gateway reaps
+ // it at streamIdleTimeout (300s) instead of its 1200s hard cap.
const rawMcpHandler = createMcpHandler((mcpContext) => createMcpServer(mcpContext), {
keepAliveMs: 0,
onerror: (error) => console.error("MCP handler error:", error),
@@ -497,6 +569,29 @@ async function main() {
return;
}
+ // A cancelled request deliberately produces no protocol response, but
+ // the SDK's legacy stateless transport still waits for one before it
+ // closes the batch's POST stream. Consume request/cancellation pairs
+ // that occur in the same batch before SDK dispatch. This applies the
+ // cancellation without starting the tool and without leaving an ID in
+ // the transport's response accounting. Only POST carries messages;
+ // other methods keep the SDK's own method handling (405). A batch that
+ // is fully consumed is answered here, before the SDK's Accept check.
+ const filteredBody =
+ req.method === "POST"
+ ? filterBatchSelfCancellations(req.body)
+ : { body: req.body, removedSelfCancellation: false };
+ if (filteredBody.removedSelfCancellation) {
+ recordSelfCancellingBatch(req.headers["user-agent"]);
+ }
+ if (
+ filteredBody.removedSelfCancellation &&
+ Array.isArray(filteredBody.body) &&
+ filteredBody.body.length === 0
+ ) {
+ return res.status(202).end();
+ }
+
const context: ClientContext = {
clientIp: req.ip,
apiKey,
@@ -515,7 +610,7 @@ async function main() {
});
await requestContext.run(context, async () => {
- await nodeHandler(req, res, req.body);
+ await nodeHandler(req, res, filteredBody.body);
});
} catch (error) {
console.error("Error handling MCP request:", error);
diff --git a/packages/mcp/src/lib/telemetry-runtime.ts b/packages/mcp/src/lib/telemetry-runtime.ts
index 7b666f78..53b0255f 100644
--- a/packages/mcp/src/lib/telemetry-runtime.ts
+++ b/packages/mcp/src/lib/telemetry-runtime.ts
@@ -106,6 +106,10 @@ export function recordAuthenticationEvent(observation: AuthenticationEventObserv
implementation?.recordAuthenticationEvent(observation);
}
+export function recordSelfCancellingBatch(userAgent: string | undefined): void {
+ implementation?.recordSelfCancellingBatch(userAgent);
+}
+
export async function observeUpstreamRequest<T>(
operationName: UpstreamOperation,
request: () => Promise<Response>,
diff --git a/packages/mcp/src/lib/telemetry.ts b/packages/mcp/src/lib/telemetry.ts
index 8942c10c..06ca0213 100644
--- a/packages/mcp/src/lib/telemetry.ts
+++ b/packages/mcp/src/lib/telemetry.ts
@@ -61,6 +61,10 @@ function createInstruments() {
description: "Number of hosted MCP authentication lifecycle events",
unit: "{event}",
}),
+ selfCancellingBatches: meter.createCounter("context7.mcp.batches.self_cancelling", {
+ description: "JSON-RPC batches in which a request was cancelled by the same batch",
+ unit: "{batch}",
+ }),
authenticationDuration: meter.createHistogram("context7.mcp.authentication.duration", {
description: "Duration of hosted MCP authentication decisions",
unit: "s",
@@ -256,6 +260,23 @@ export async function observeAuthentication<T extends AuthenticationObservation>
}
}
+const MAX_BATCH_CLIENT_NAMES = 50;
+const batchClientNames = new Set<string>();
+
+/**
+ * Counts a batch that cancelled its own request, by the product token of the
+ * caller's User-Agent. The header is caller-controlled, so the label set is
+ * capped per process; later names are counted as "other".
+ */
+export function recordSelfCancellingBatch(userAgent: string | undefined): void {
+ let client = /^[\w.-]{1,40}/.exec(userAgent ?? "")?.[0].toLowerCase() ?? "unknown";
+ if (!batchClientNames.has(client)) {
+ if (batchClientNames.size >= MAX_BATCH_CLIENT_NAMES) client = "other";
+ else batchClientNames.add(client);
+ }
+ getInstruments().selfCancellingBatches.add(1, { "user_agent.name": client });
+}
+
export function recordAuthenticationEvent(observation: AuthenticationEventObservation): void {
const attributes: Attributes = {
"context7.authentication.enforcement": observation.enforcementMode,
diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.ts
index f415cd4a..1b547f0c 100644
--- a/packages/mcp/test/integration.test.ts
+++ b/packages/mcp/test/integration.test.ts
@@ -466,6 +466,175 @@ describe("HTTP API key headers", () => {
});
});
+describe("HTTP batch cancellation", () => {
+ beforeEach(() => {
+ requests.length = 0;
+ });
+
+ test("consumes a request cancelled by the same batch and closes promptly", async () => {
+ const response = await fetch(httpUrl, {
+ method: "POST",
+ headers: {
+ "content-type": "application/json",
+ accept: "application/json, text/event-stream",
+ authorization: "Bearer ctx7sk-local-test",
+ },
+ body: JSON.stringify([
+ {
+ jsonrpc: "2.0",
+ id: 102,
+ method: "tools/call",
+ params: {
+ name: "resolve-library-id",
+ arguments: { query: "framework documentation", libraryName: "Next.js" },
+ },
+ },
+ {
+ jsonrpc: "2.0",
+ method: "notifications/cancelled",
+ params: { requestId: 102, reason: "regression-test" },
+ },
+ ]),
+ signal: AbortSignal.timeout(1_000),
+ });
+
+ expect(response.status).toBe(202);
+ expect(await response.text()).toBe("");
+ expect(requests).toHaveLength(0);
+ });
+
+ test("returns responses for the uncancelled requests in a mixed batch", async () => {
+ const response = await fetch(httpUrl, {
+ method: "POST",
+ headers: {
+ "content-type": "application/json",
+ accept: "application/json, text/event-stream",
+ authorization: "Bearer ctx7sk-local-test",
+ },
+ body: JSON.stringify([
+ {
+ jsonrpc: "2.0",
+ id: 104,
+ method: "tools/call",
+ params: {
+ name: "resolve-library-id",
+ arguments: { query: "cancelled", libraryName: "Cancelled.js" },
+ },
+ },
+ {
+ jsonrpc: "2.0",
+ id: 105,
+ method: "tools/call",
+ params: {
+ name: "resolve-library-id",
+ arguments: { query: "framework documentation", libraryName: "Next.js" },
+ },
+ },
+ {
+ jsonrpc: "2.0",
+ method: "notifications/cancelled",
+ params: { requestId: 104, reason: "regression-test" },
+ },
+ ]),
+ signal: AbortSignal.timeout(1_000),
+ });
+
+ expect(response.status).toBe(200);
+ const responseText = await response.text();
+ expect(responseText).not.toContain('"id":104');
+ expect(responseText).toContain('"id":105');
+ expect(requests.filter((request) => request.path === "/v2/libs/search")).toHaveLength(1);
+ expect(requests[0].query.get("libraryName")).toBe("Next.js");
+ });
+
+ test("allows a cancellation for an ID outside the batch", async () => {
+ const response = await fetch(httpUrl, {
+ method: "POST",
+ headers: {
+ "content-type": "application/json",
+ accept: "application/json, text/event-stream",
+ authorization: "Bearer ctx7sk-local-test",
+ },
+ body: JSON.stringify([
+ {
+ jsonrpc: "2.0",
+ id: 103,
+ method: "tools/call",
+ params: {
+ name: "resolve-library-id",
+ arguments: { query: "framework documentation", libraryName: "Next.js" },
+ },
+ },
+ {
+ jsonrpc: "2.0",
+ method: "notifications/cancelled",
+ params: { requestId: 999, reason: "different-request" },
+ },
+ ]),
+ signal: AbortSignal.timeout(1_000),
+ });
+
+ expect(response.status).toBe(200);
+ expect(await response.text()).toContain('"id":103');
+ expect(requests.filter((request) => request.path === "/v2/libs/search")).toHaveLength(1);
+ });
+
+ test("leaves a batch with a 2026-07-28 element to the SDK, which rejects it", async () => {
+ const modernParams = { _meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } };
+ const response = await fetch(httpUrl, {
+ method: "POST",
+ headers: {
+ "content-type": "application/json",
+ accept: "application/json, text/event-stream",
+ authorization: "Bearer ctx7sk-local-test",
+ },
+ body: JSON.stringify([
+ { jsonrpc: "2.0", id: 107, method: "tools/list", params: modernParams },
+ {
+ jsonrpc: "2.0",
+ method: "notifications/cancelled",
+ params: { requestId: 107, reason: "regression-test" },
+ },
+ {
+ jsonrpc: "2.0",
+ id: 108,
+ method: "tools/call",
+ params: {
+ name: "resolve-library-id",
+ arguments: { query: "framework documentation", libraryName: "Next.js" },
+ },
+ },
+ ]),
+ signal: AbortSignal.timeout(1_000),
+ });
+
+ expect(response.status).toBe(400);
+ expect(requests).toHaveLength(0);
+ });
+
+ test("keeps 405 for a self-cancelling batch sent with DELETE", async () => {
+ const response = await fetch(httpUrl, {
+ method: "DELETE",
+ headers: {
+ "content-type": "application/json",
+ accept: "application/json, text/event-stream",
+ authorization: "Bearer ctx7sk-local-test",
+ },
+ body: JSON.stringify([
+ { jsonrpc: "2.0", id: 106, method: "tools/list" },
+ {
+ jsonrpc: "2.0",
+ method: "notifications/cancelled",
+ params: { requestId: 106, reason: "regression-test" },
+ },
+ ]),
+ signal: AbortSignal.timeout(1_000),
+ });
+
+ expect(response.status).toBe(405);
+ });
+});
+
describe.each([
["http", "modern"],
["http", "legacy"],