Publish a Server Card and an AI Catalog for your MCP server, Beta
Before you start
A client can read two public JSON documents to learn about your MCP server before it connects or signs in:
- A Server Card describes one MCP server: its name, version, description, and the URL to connect to. The recommended path is your MCP endpoint's URL followed by
/server-card, such as/mcp/server-card. - An AI Catalog lists the Server Cards on your domain, at
/.well-known/ard.jsonand/.well-known/ai-catalog.json.
@clerk/mcp-tools serves both with serverCardHandler() and aiCatalogHandler(). Both specifications are drafts, and so are these APIs. They follow the Server Card extension as of commit 526201b and the AI Catalog v0.9 release candidate as of commit 19208af. They may change in a later release. Publishing these documents doesn't guarantee that every MCP host will find or use them.
This guide adds both documents to the MCP server from Build an MCP server.
Install the required version
serverCardHandler() and aiCatalogHandler() require @clerk/mcp-tools 1.0.0 or later. They don't need Clerk keys or the MCP SDK.
npm install @clerk/mcp-tools@latestpnpm add @clerk/mcp-tools@latestyarn add @clerk/mcp-tools@latestbun add @clerk/mcp-tools@latestServe a Server Card
A Server Card needs:
name: the server's name in reverse-DNS form with one slash, such ascom.example/profile. It identifies the server and isn't a URL.version: one version, such as1.0.0, not a range.description: 1 to 100 characters.resourceUrl: the URL clients connect to. Pass theresourceUrlfrommcpAuthOptions, so the card and the token audience check use the same URL.
You can also set title, websiteUrl, icons, repository, and _meta. The handler adds $schema and a streamable HTTP remotes entry for resourceUrl. When you create the handler, it validates the options and builds the card once. It throws a Clerk error: for anything the card can't contain.
The card is public and cached, so never put credentials, tokens, or user data in it.
In index.ts, mount serverCardHandler() with app.all(), so OPTIONS and other methods reach it. Mount it outside mcpAuth().
// ...
app.all(
'/mcp/server-card',
serverCardHandler({
name: 'com.example/profile',
version: '1.0.0',
description: 'Returns the ID of the signed-in Clerk user.',
resourceUrl: mcpAuthOptions.resourceUrl,
}),
)
app.listen(3000)Add serverCardHandler to the imports from @clerk/mcp-tools/express.
Serve an AI Catalog
An AI Catalog lists one entry for each Server Card:
identifier: a name for the server that stays the same wherever its card is hosted, such asurn:air:example.com:profile. It isn't a URL, and each identifier can appear only once.displayName: the server's human-readable name. Clients show it instead of the card'stitle, so keep the two the same.url: the exact URL of the Server Card, which can be on another host. It must usehttps, except onlocalhost,127.0.0.1, or[::1]for local development. The handler never fetches it.
Agentic Resource Discovery defines /.well-known/ard.json as the path clients fetch. Some clients still read the earlier path, /.well-known/ai-catalog.json. Serve the same handler at both.
In index.ts, mount aiCatalogHandler() at both paths with app.all(), outside mcpAuth().
// ...
app.all(
['/.well-known/ard.json', '/.well-known/ai-catalog.json'],
aiCatalogHandler({
entries: [
{
identifier: 'urn:air:example.com:profile',
displayName: 'Profile',
url: 'http://localhost:3000/mcp/server-card',
},
],
}),
)
app.listen(3000)Add aiCatalogHandler to the imports from @clerk/mcp-tools/express.
When you deploy, replace the localhost URLs with your server's HTTPS URLs.
Keep the discovery routes public
Clients read these documents before they sign in, so a request without a token must reach them.
Don't mount mcpAuth() or other authentication in front of /mcp/server-card, /.well-known/ard.json, or /.well-known/ai-catalog.json.
Test the documents
Start your server, then request the card and the catalog:
curl -i http://localhost:3000/mcp/server-card
curl -i http://localhost:3000/.well-known/ard.jsonThe card's Content-Type is application/mcp-server-card+json, and the catalog's is application/ai-catalog+json.
How the handlers answer
GETandHEADget the document with a weakETagandCache-Control: public, max-age=3600. To change the cache lifetime, setmaxAgeto a number of seconds.0sendspublic, no-cache, so caches revalidate the document before each use.- A request whose
If-None-Matchmatches theETaggets a304without a body. - Any origin can read the documents. The handlers send
Access-Control-Allow-Origin: *and answer theOPTIONSpreflight. Other methods get a JSON405. - Errors are sent with
Cache-Control: no-store, so no cache keeps them. - If
mcpAuthOptions.resourceUrlis a list of URLs, one for each origin,serverCardHandler()serves the card for the URL that matches the request's origin. Any other origin gets a421. The AI Catalog returns the same document for every request. To link a different card from each origin, create oneaiCatalogHandler()per origin.
Limitations
- The handlers support a subset of each specification. A Server Card can't list SSE remotes, URL templates, or header inputs. An AI Catalog entry can only link a Server Card, and the catalog can't carry inline documents, signatures, or extensions.
- An AI Catalog entry can carry an optional
trustManifestthat names who stands behind the server. List only claims you can back. See the@clerk/mcp-toolsREADME for its fields.
Feedback
Last updated on