Skip to content

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

CTX7-3207: Update MCP SDK to 2.3.1, add list cache hints, flag resolve errors, drain HTTP on shutdown (#3435)

Enes Gules1b00727f345b
diff --git a/.changeset/mcp-sdk-2-3-cache-hints.md b/.changeset/mcp-sdk-2-3-cache-hints.md
new file mode 100644
index 00000000..8d2248b7
--- /dev/null
+++ b/.changeset/mcp-sdk-2-3-cache-hints.md
@@ -0,0 +1,7 @@
+---
+"@upstash/context7-mcp": patch
+---
+
+Update the MCP SDK to `@modelcontextprotocol/server` 2.3.1 and `@modelcontextprotocol/node` 2.1.1, which converts tool schemas lazily, so each per-request server costs less to build. On the 2026-07-28 protocol, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list` and `server/discover` now return `ttlMs: 3600000` and `cacheScope: "public"`, so clients can reuse them for an hour instead of listing on every request. `resolve-library-id` now sets `isError: true` when the library search fails; a search with no matches is still a normal result.
+
+On SIGTERM the HTTP server now finishes the requests on open connections before it closes the MCP handler, and answers them with `Connection: close`. Before, those requests got HTTP 499 or 500 from the closed handler, and the shutdown hit its 5 s limit and exited with code 1. The SDK's rejections of malformed client requests are now logged as one line without a stack trace.
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
index 4d41c775..37f2758f 100644
--- a/packages/mcp/package.json
+++ b/packages/mcp/package.json
@@ -46,8 +46,8 @@
},
"homepage": "https://github.com/upstash/context7#readme",
"dependencies": {
- "@modelcontextprotocol/node": "2.1.0",
- "@modelcontextprotocol/server": "2.2.0",
+ "@modelcontextprotocol/node": "2.1.1",
+ "@modelcontextprotocol/server": "2.3.1",
"@opentelemetry/api": "^1.9.1",
"@opentelemetry/exporter-prometheus": "^0.222.0",
"@opentelemetry/instrumentation-runtime-node": "^0.35.0",
@@ -61,7 +61,7 @@
"zod": "^4.6.5"
},
"devDependencies": {
- "@modelcontextprotocol/client": "2.2.0",
+ "@modelcontextprotocol/client": "2.3.1",
"@opentelemetry/context-async-hooks": "^2.11.0",
"@opentelemetry/core": "^2.11.0",
"@opentelemetry/sdk-trace-base": "^2.11.0",
diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts
index b9ac7b7e..07149e75 100644
--- a/packages/mcp/src/index.ts
+++ b/packages/mcp/src/index.ts
@@ -62,6 +62,7 @@ import { parseOAuthAudienceEnforcement } from "./lib/oauth-audience.js";
const DEFAULT_PORT = 3000;
const OAUTH_METADATA_TIMEOUT_MS = 10_000;
const CLAUDE_CODE_PLUGIN = "claude-code-plugin";
+const STATIC_LIST_CACHE_HINT = { ttlMs: 3_600_000, cacheScope: "public" } as const;
type McpInstrumentation = NonNullable<Awaited<ReturnType<typeof initializeTelemetry>>>;
let mcpInstrumentation: McpInstrumentation | undefined;
@@ -277,6 +278,17 @@ function createMcpServer(mcpContext: McpRequestContext) {
prompts: { listChanged: false },
resources: { listChanged: false, subscribe: false },
},
+ // These results are the same for every caller and change only on deploy, so
+ // clients may reuse them for an hour instead of listing on every request.
+ // After a deploy that changes a tool schema, clients can still call with the
+ // old schema for that hour: keep old argument names accepted (aliasArgs).
+ cacheHints: {
+ "tools/list": STATIC_LIST_CACHE_HINT,
+ "prompts/list": STATIC_LIST_CACHE_HINT,
+ "resources/list": STATIC_LIST_CACHE_HINT,
+ "resources/templates/list": STATIC_LIST_CACHE_HINT,
+ "server/discover": STATIC_LIST_CACHE_HINT,
+ },
instructions: `Use this server to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.
Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.`,
@@ -359,6 +371,8 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
text,
},
],
+ // Same rule as query-docs: an upstream failure is an error, an empty match is not.
+ ...(searchResponse.error ? { isError: true } : {}),
};
}
@@ -458,10 +472,14 @@ async function main() {
// then walks the chain right-to-left and ignores attacker-added prefixes.
app.set("trust proxy", ["loopback", "linklocal", "uniquelocal", "100.64.0.0/10"]);
+ // Node keeps serving requests on kept-alive sockets after server.close(),
+ // so during shutdown every response asks the gateway to reconnect elsewhere.
+ let shuttingDown = false;
// Registered ahead of the MCP router so its error responses carry the CORS
// headers too; browser clients would otherwise see a CORS failure instead
// of the status.
app.use((req: express.Request, res: express.Response, next: express.NextFunction) => {
+ if (shuttingDown) res.setHeader("Connection", "close");
res.setHeader("Access-Control-Allow-Origin", "*");
res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,DELETE");
// Mcp-Method / Mcp-Name are the SEP-2243 standard headers 2026-07-28
@@ -524,7 +542,16 @@ async function main() {
// 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),
+ // The SDK reports each 4xx answer to a malformed client request as a new
+ // Error whose stack only names SDK internals, so those log
+ // their message alone. If the SDK rewords them, the stacks come back.
+ onerror: (error) =>
+ console.error(
+ "MCP handler error:",
+ error instanceof Error && /^(Rejected |Unsupported Media Type)/.test(error.message)
+ ? error.message
+ : error
+ ),
});
const mcpHandler = mcpInstrumentation
? mcpInstrumentation.instrumentHttpHandler(rawMcpHandler)
@@ -741,25 +768,23 @@ async function main() {
installProcessShutdown(
{
close: async () => {
+ shuttingDown = true;
const server = activeHttpServer;
- const operations: Promise<void>[] = [mcpHandler.close()];
+ // Drain HTTP before closing the MCP handler: requests that still
+ // arrive on open sockets would otherwise get a 500 from the closed
+ // handler.
if (server) {
- operations.unshift(
- new Promise<void>((resolve, reject) => {
- server.close((error) => {
- if (error) reject(error);
- else resolve();
- });
- })
- );
- }
- const results = await Promise.allSettled(operations);
- const failures = results
- .filter((result): result is PromiseRejectedResult => result.status === "rejected")
- .map((result) => result.reason);
- if (failures.length > 0) {
- throw new AggregateError(failures, "MCP HTTP server failed to close cleanly");
+ // A response that began before SIGTERM has no Connection: close, so
+ // its socket then idles for keepAliveTimeout (5 s by default) and
+ // server.close() waits for it. Node reads the timeout when a socket
+ // goes idle, so this also covers responses already running.
+ server.keepAliveTimeout = 1_000;
+ await new Promise<void>((resolve, reject) => {
+ server.close((error) => (error ? reject(error) : resolve()));
+ server.closeIdleConnections();
+ });
}
+ await mcpHandler.close();
},
},
{
diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.ts
index 1b547f0c..0ce99edd 100644
--- a/packages/mcp/test/integration.test.ts
+++ b/packages/mcp/test/integration.test.ts
@@ -24,6 +24,7 @@ const STUB_DOCS = "stub docs text";
const EMPTY_CONTEXT_QUERY = "force-empty-context";
const NO_RESULTS_QUERY = "force-no-results";
const UPSTREAM_ERROR_QUERY = "force-upstream-error";
+const SLOW_CONTEXT_QUERY = "force-slow-context";
const INVALID_JSON_QUERY = "force-invalid-json";
const CLIENT_IP_ASSERTION_KEY = "0123456789abcdef".repeat(4);
const INVALID_OAUTH_TOKEN_BODY = {
@@ -155,6 +156,10 @@ function startStubApi(): Promise<string> {
return;
}
res.setHeader("Content-Type", "text/plain");
+ if (url.searchParams.get("query") === SLOW_CONTEXT_QUERY) {
+ setTimeout(() => res.end(STUB_DOCS), 500);
+ return;
+ }
res.end(url.searchParams.get("query") === EMPTY_CONTEXT_QUERY ? "" : STUB_DOCS);
} else {
res.statusCode = 404;
@@ -240,6 +245,91 @@ test("reports the bound port when port zero requests an ephemeral port", async (
}
});
+// A modern query-docs call over a caller-chosen agent, so tests control socket reuse.
+function callQueryDocsOver(url: string, agent: http.Agent, query: string) {
+ return new Promise<{ status: number; connection: string | undefined }>((resolve, reject) => {
+ const req = http.request(
+ url,
+ {
+ method: "POST",
+ agent,
+ headers: {
+ "content-type": "application/json",
+ accept: "application/json, text/event-stream",
+ authorization: "Bearer ctx7sk-local-test",
+ "mcp-protocol-version": "2026-07-28",
+ "mcp-method": "tools/call",
+ "mcp-name": "query-docs",
+ },
+ },
+ (res) => {
+ res.resume();
+ res.on("end", () =>
+ resolve({ status: res.statusCode!, connection: res.headers.connection })
+ );
+ }
+ );
+ req.on("error", reject);
+ req.end(
+ JSON.stringify({
+ jsonrpc: "2.0",
+ id: 1,
+ method: "tools/call",
+ params: {
+ name: "query-docs",
+ arguments: { libraryId: "/vercel/next.js", query },
+ _meta: {
+ "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+ "io.modelcontextprotocol/clientCapabilities": {},
+ },
+ },
+ })
+ );
+ });
+}
+
+describe("HTTP shutdown", () => {
+ test("serves requests that arrive on a kept-alive socket during shutdown", async () => {
+ const { child, url } = await startHttpChild({ port: 0 });
+ const exited = new Promise<number | null>((resolve) => child.once("exit", resolve));
+ // One socket, so the second request reuses the connection of the first.
+ const agent = new http.Agent({ keepAlive: true, maxSockets: 1 });
+ try {
+ const inFlight = callQueryDocsOver(url, agent, SLOW_CONTEXT_QUERY);
+ await new Promise((resolve) => setTimeout(resolve, 100));
+ child.kill("SIGTERM");
+ // Queued behind the in-flight call, so it reaches the server after SIGTERM.
+ const afterSignal = callQueryDocsOver(url, agent, "app router");
+
+ expect((await inFlight).status).toBe(200);
+ expect(await afterSignal).toEqual({ status: 200, connection: "close" });
+ expect(await exited).toBe(0);
+ } finally {
+ agent.destroy();
+ child.kill();
+ }
+ });
+
+ test("exits cleanly when a request in flight at SIGTERM leaves its socket open", async () => {
+ const { child, url } = await startHttpChild({ port: 0 });
+ const exited = new Promise<number | null>((resolve) => child.once("exit", resolve));
+ const agent = new http.Agent({ keepAlive: true });
+ try {
+ const inFlight = callQueryDocsOver(url, agent, SLOW_CONTEXT_QUERY);
+ await new Promise((resolve) => setTimeout(resolve, 100));
+ child.kill("SIGTERM");
+
+ // The response began before SIGTERM, so it keeps the socket alive and the
+ // client sends nothing more; shutdown must still finish inside its limit.
+ expect(await inFlight).toEqual({ status: 200, connection: "keep-alive" });
+ expect(await exited).toBe(0);
+ } finally {
+ agent.destroy();
+ child.kill();
+ }
+ });
+});
+
async function connect(transportKind: "http" | "stdio", era: "modern" | "legacy") {
const client = new Client(
{ name: "test-harness", version: "1.0.0" },
@@ -720,6 +810,20 @@ describe.each([
expect(text).toContain("stub upstream failure");
});
+ test("flags a failed resolve-library-id search as an error, not an empty match", async () => {
+ const failed = await client.callTool({
+ name: "resolve-library-id",
+ arguments: { libraryName: "Next.js", query: INVALID_JSON_QUERY },
+ });
+ expect(failed.isError).toBe(true);
+
+ const empty = await client.callTool({
+ name: "resolve-library-id",
+ arguments: { libraryName: "does-not-exist", query: NO_RESULTS_QUERY },
+ });
+ expect(empty.isError).toBeFalsy();
+ });
+
test("calls resolve-library-id end to end", async () => {
const result = await client.callTool({
name: "resolve-library-id",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index efc0e654..22b0e28f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -152,11 +152,11 @@ importers:
packages/mcp:
dependencies:
'@modelcontextprotocol/node':
- specifier: 2.1.0
- version: 2.1.0(@modelcontextprotocol/[email protected])([email protected])
+ specifier: 2.1.1
+ version: 2.1.1(@modelcontextprotocol/[email protected])
'@modelcontextprotocol/server':
- specifier: 2.2.0
- version: 2.2.0
+ specifier: 2.3.1
+ version: 2.3.1
'@opentelemetry/api':
specifier: ^1.9.1
version: 1.9.1
@@ -192,8 +192,8 @@ importers:
version: 4.6.5
devDependencies:
'@modelcontextprotocol/client':
- specifier: 2.2.0
- version: 2.2.0
+ specifier: 2.3.1
+ version: 2.3.1
'@opentelemetry/context-async-hooks':
specifier: ^2.11.0
version: 2.11.0(@opentelemetry/[email protected])
@@ -1386,23 +1386,19 @@ packages:
resolution: {integrity: sha512-ABnA53mdfkGZwOFUdZNv2S0CWGO/EIuPj8Vv9xmBFmSYg/qFc7ihO6q5FcQjvoE67kZpWkEc4AhD6B/os04yuA==}
engines: {node: '>= 10'}
- '@modelcontextprotocol/[email protected]':
- resolution: {integrity: sha512-LxCou/CSYQ6dwEnjhLZY0KnEuc8V4UJ3IEQCl/uR2yHobSQIEdJKUlKLRYRF5i5FqRGHy1eK7une3aAWDHLtig==}
+ '@modelcontextprotocol/[email protected]':
+ resolution: {integrity: sha512-mIGZXpHsjnZ6lD+gD/WCMpR5k8yVQQ8nNFH1N0Srf7AvnwTUMYD6pvTY8ng2+He5FfV7YMZLmrjL7cLa/cc3dQ==}
engines: {node: '>=20'}
- '@modelcontextprotocol/[email protected]':
- resolution: {integrity: sha512-iLhmprRmWI8EcosOA3wVvww22z02NkgqhV4fBH6f/odQBsi7xnJc0HGmi21yWO+/iKw2yzqVE127Zhna5/+JXw==}
+ '@modelcontextprotocol/[email protected]':
+ resolution: {integrity: sha512-laVmIhPGpWi7rG9q+0UigblRN0Hws/Yjlb6qLFtVqryXVLkc4h+yN8z731POD2LnAGQlFe7/tXhUm7Bi0YB91g==}
engines: {node: '>=20'}
- '@modelcontextprotocol/[email protected]':
- resolution: {integrity: sha512-6xg3iWVcOfiL8Y7rI6xUqXD0lI2AY5q3djsa/cOi1IJUSwx06t0gvhSwU/6mIIohrFlt40/ANUG56DQ0HLhILQ==}
+ '@modelcontextprotocol/[email protected]':
+ resolution: {integrity: sha512-EY92OAXN2xYL7tNS/MVsWJW1v8VHAPwl9B4Ca3pCrjmvqyC+S1C/6UHsMxF2GoFPraS5Yyg56vFz9brVpFojMA==}
engines: {node: '>=20'}
peerDependencies:
- '@modelcontextprotocol/server': ^2.1.0
- hono: ^4.11.4
- peerDependenciesMeta:
- hono:
- optional: true
+ '@modelcontextprotocol/server': ^2.3.0
'@modelcontextprotocol/[email protected]':
resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
@@ -1414,8 +1410,8 @@ packages:
'@cfworker/json-schema':
optional: true
- '@modelcontextprotocol/[email protected]':
- resolution: {integrity: sha512-qFnltjus6Gk8Lx6J1w2RXmr3YPN22MNT6qD6zjAkaiWIlFIFxWClz0rXHNuJF/KSUyn5YGhkSvXkWDbQHVLFEQ==}
+ '@modelcontextprotocol/[email protected]':
+ resolution: {integrity: sha512-e59MfWuSssj6DoQ96JCTqdW1AXT5/XtnTl0WWd6MU1Ka434fFUGGosCLJbGNySDhHGvxQWoRWK137FXYFkYNWw==}
engines: {node: '>=20'}
'@msgpackr-extract/[email protected]':
@@ -2173,9 +2169,6 @@ packages:
resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}
- resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==}
-
resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}
@@ -2561,6 +2554,10 @@ packages:
resolution: {integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==}
engines: {node: '>=18.0.0'}
+ resolution: {integrity: sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==}
+ engines: {node: '>=18.0.0'}
+
resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
engines: {node: '>=18.0.0'}
@@ -4952,32 +4949,31 @@ snapshots:
'@mariozechner/clipboard-win32-x64-msvc': 0.3.9
optional: true
- '@modelcontextprotocol/[email protected]':
+ '@modelcontextprotocol/[email protected]':
dependencies:
- '@modelcontextprotocol/core': 2.2.0
+ '@modelcontextprotocol/core': 2.3.1
cross-spawn: 7.0.6
eventsource: 3.0.7
- eventsource-parser: 3.0.6
+ eventsource-parser: 3.1.1
jose: 6.2.12
pkce-challenge: 5.0.0
zod: 4.6.5
- '@modelcontextprotocol/[email protected]':
+ '@modelcontextprotocol/[email protected]':
dependencies:
zod: 4.6.5
- '@modelcontextprotocol/[email protected](@modelcontextprotocol/[email protected])([email protected])':
+ '@modelcontextprotocol/[email protected](@modelcontextprotocol/[email protected])':
dependencies:
'@hono/node-server': 1.19.14([email protected])
- '@modelcontextprotocol/server': 2.2.0
- optionalDependencies:
+ '@modelcontextprotocol/server': 2.3.1
hono: 4.12.23
'@modelcontextprotocol/[email protected]([email protected])':
dependencies:
'@hono/node-server': 1.19.14([email protected])
- ajv: 8.17.1
- ajv-formats: 3.0.1([email protected])
+ ajv: 8.20.0
+ ajv-formats: 3.0.1([email protected])
content-type: 1.0.5
cors: 2.8.5
cross-spawn: 7.0.6
@@ -4996,9 +4992,9 @@ snapshots:
- supports-color
optional: true
- '@modelcontextprotocol/[email protected]':
+ '@modelcontextprotocol/[email protected]':
dependencies:
- '@modelcontextprotocol/core': 2.2.0
+ '@modelcontextprotocol/core': 2.3.1
zod: 4.6.5
'@msgpackr-extract/[email protected]':
@@ -5815,11 +5811,6 @@ snapshots:
'@opentelemetry/api': 1.9.0
zod: 4.6.5
- optionalDependencies:
- ajv: 8.17.1
- optional: true
-
optionalDependencies:
ajv: 8.20.0
@@ -5831,14 +5822,6 @@ snapshots:
json-schema-traverse: 0.4.1
uri-js: 4.4.1
- dependencies:
- fast-deep-equal: 3.1.3
- fast-uri: 3.1.0
- json-schema-traverse: 1.0.0
- require-from-string: 2.0.2
- optional: true
-
dependencies:
fast-deep-equal: 3.1.3
@@ -6281,9 +6264,11 @@ snapshots:
+
dependencies:
- eventsource-parser: 3.0.6
+ eventsource-parser: 3.1.1