Skip to content

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

Serve the MCP server card and fix README tool names (#3197)

Enes Gules72181dd4ac5b
diff --git a/.changeset/mcp-discovery-compat.md b/.changeset/mcp-discovery-compat.md
new file mode 100644
index 00000000..fd8ed81a
--- /dev/null
+++ b/.changeset/mcp-discovery-compat.md
@@ -0,0 +1,5 @@
+---
+"@upstash/context7-mcp": patch
+---
+
+Serve a SEP-2127 server card at `/mcp/server-card`.
diff --git a/packages/mcp/README.md b/packages/mcp/README.md
index 679da158..2dbd2581 100644
--- a/packages/mcp/README.md
+++ b/packages/mcp/README.md
@@ -1017,7 +1017,7 @@ Add the following configuration to the `mcp` section of your Copilot Coding Agen
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
},
- "tools": ["get-library-docs", "resolve-library-id"]
+ "tools": ["query-docs", "resolve-library-id"]
}
}
}
@@ -1042,7 +1042,7 @@ For more information, see the [official GitHub documentation](https://docs.githu
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
},
- "tools": ["get-library-docs", "resolve-library-id"]
+ "tools": ["query-docs", "resolve-library-id"]
}
}
}
@@ -1056,7 +1056,7 @@ Or, for a local server:
"context7": {
"type": "local",
"command": "npx",
- "tools": ["get-library-docs", "resolve-library-id"],
+ "tools": ["query-docs", "resolve-library-id"],
"args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
}
}
@@ -1194,7 +1194,7 @@ Open the "Settings" page of the app, navigate to "Plugins," and enter the follow
}
```
-Once saved, enter in the chat `get-library-docs` followed by your Context7 documentation ID (e.g., `get-library-docs /nuxt/ui`). More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). For BoltAI on iOS, [see this guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers).
+Once saved, enter in the chat `query-docs` followed by your Context7 documentation ID (e.g., `query-docs /nuxt/ui how to set up a theme`). More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). For BoltAI on iOS, [see this guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers).
</details>
@@ -1391,11 +1391,13 @@ Context7 MCP provides the following tools that LLMs can use:
- `resolve-library-id`: Resolves a general library name into a Context7-compatible library ID.
- `libraryName` (required): The name of the library to search for
+ - `query` (required): What you need the docs for, used to rank matches
-- `get-library-docs`: Fetches documentation for a library using a Context7-compatible library ID.
- - `context7CompatibleLibraryID` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`)
- - `topic` (optional): Focus the docs on a specific topic (e.g., "routing", "hooks")
- - `page` (optional, default 1): Page number for pagination (1-10). If the context is not sufficient, try page=2, page=3, etc. with the same topic.
+- `query-docs`: Queries up-to-date documentation and code examples for a Context7-compatible library ID.
+ - `libraryId` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`)
+ - `query` (required): The concept to look up, scoped to a single topic
+
+`get-library-docs` was renamed to `query-docs`. Update client tool allowlists to use `query-docs`.
## 🛟 Tips
diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts
index 1930ac5a..ff82d09f 100644
--- a/packages/mcp/src/index.ts
+++ b/packages/mcp/src/index.ts
@@ -27,6 +27,7 @@ import {
OAUTH_AUTH_SERVER_URL,
EMA_ISSUER,
OPENAI_APPS_CHALLENGE_TOKEN,
+ mcpServerCard,
} from "./lib/constants.js";
import { maybeElicitAuthSignIn } from "./lib/auth/auth-prompt.js";
import { QUERY_DOCS_TOOL, RESOLVE_LIBRARY_ID_TOOL } from "./lib/tool-names.js";
@@ -381,7 +382,7 @@ async function main() {
// browser clients, so those are not needed.)
res.setHeader(
"Access-Control-Allow-Headers",
- "Content-Type, MCP-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization"
+ "Content-Type, MCP-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization, If-None-Match"
);
if (req.method === "OPTIONS") {
res.sendStatus(200);
@@ -529,6 +530,16 @@ async function main() {
mcpRouter.all("/", (req, res) => handleMcpRequest(req, res));
// OAuth-protected endpoint - requires authentication
mcpRouter.all("/oauth", (req, res) => handleMcpRequest(req, res));
+
+ // SEP-2127 reserves `{streamable-http-url}/server-card`. Register it
+ // before the /mcp router so it is not answered as MCP JSON-RPC.
+ app.get("/mcp/server-card", (_req: express.Request, res: express.Response) => {
+ res.setHeader("Content-Type", "application/mcp-server-card+json");
+ res.setHeader("Cache-Control", "public, max-age=3600");
+ res.setHeader("Access-Control-Expose-Headers", "ETag");
+ // Express adds the ETag and answers a matching If-None-Match with 304.
+ res.status(200).send(mcpServerCard());
+ });
app.use("/mcp", mcpRouter);
app.get("/ping", (_req: express.Request, res: express.Response) => {
diff --git a/packages/mcp/src/lib/constants.ts b/packages/mcp/src/lib/constants.ts
index f22cc9c3..f336ffb2 100644
--- a/packages/mcp/src/lib/constants.ts
+++ b/packages/mcp/src/lib/constants.ts
@@ -33,3 +33,40 @@ export const EMA_ISSUER =
process.env.EMA_ISSUER || process.env.AUTH_SERVER_URL || CONTEXT7_BASE_URL;
export const EMA_JWKS_URL = process.env.EMA_JWKS_URL || `${CONTEXT7_API_BASE_URL}/oauth/ema-jwks`;
export const OPENAI_APPS_CHALLENGE_TOKEN = process.env.OPENAI_APPS_CHALLENGE_TOKEN;
+
+/** Describe the remote server using the experimental Server Card v1 schema. */
+export function mcpServerCard(resourceUrl = RESOURCE_URL) {
+ return {
+ $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+ name: "io.github.upstash/context7",
+ title: "Context7",
+ description:
+ "Up-to-date, version-specific documentation and code examples for software libraries.",
+ version: SERVER_VERSION,
+ websiteUrl: "https://context7.com",
+ icons: [{ src: "https://context7.com/context7-icon-green.png", mimeType: "image/png" }],
+ remotes: [
+ {
+ type: "streamable-http",
+ url: `${new URL(resourceUrl).origin}/mcp`,
+ headers: [
+ {
+ name: "Authorization",
+ description:
+ "Optional. A Context7 API key from https://context7.com/dashboard raises the rate limit.",
+ isRequired: false,
+ isSecret: true,
+ value: "Bearer {api_key}",
+ variables: {
+ api_key: {
+ description: "Context7 API key",
+ isSecret: true,
+ placeholder: "ctx7sk-...",
+ },
+ },
+ },
+ ],
+ },
+ ],
+ };
+}
diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.ts
index cff8bf91..4292d0d0 100644
--- a/packages/mcp/test/integration.test.ts
+++ b/packages/mcp/test/integration.test.ts
@@ -221,6 +221,42 @@ describe("OAuth discovery", () => {
authorization_servers: ["https://clerk.context7.com", "https://context7.com"],
});
});
+
+ test("serves the SEP-2127 server card at /mcp/server-card", async () => {
+ const response = await fetch(new URL("/mcp/server-card", httpUrl));
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get("content-type")).toMatch(/application\/mcp-server-card\+json/);
+ const card = await response.json();
+ expect(card).toMatchObject({
+ $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+ name: "io.github.upstash/context7",
+ remotes: [{ type: "streamable-http", url: "https://mcp.context7.com/mcp" }],
+ });
+ expect(card.description.length).toBeLessThanOrEqual(100);
+ expect(card.remotes[0].headers).toEqual([
+ expect.objectContaining({ name: "Authorization", isRequired: false, isSecret: true }),
+ ]);
+ expect(response.headers.get("cache-control")).toBe("public, max-age=3600");
+ expect(response.headers.get("access-control-expose-headers")).toBe("ETag");
+
+ const etag = response.headers.get("etag");
+ expect(etag).toBeTruthy();
+ // node:http, because fetch adds Cache-Control: no-cache to conditional requests.
+ const status = await new Promise<number | undefined>((resolve, reject) => {
+ http
+ .get(
+ new URL("/mcp/server-card", httpUrl),
+ { headers: { "If-None-Match": etag! } },
+ (res) => {
+ res.resume();
+ resolve(res.statusCode);
+ }
+ )
+ .on("error", reject);
+ });
+ expect(status).toBe(304);
+ });
});
// A malformed body fails inside express.json(), which calls next(err). That