How to publish /.well-known/mcp/server-card.json on Docusaurus

Docusaurus serves anything in static/ as-is, so the MCP server card needs one file and no plugin. This guide covers check P2 on Docusaurus. I built a site on Docusaurus 3.10.2 and ran the dev server and the production server, and the dev server hides the one mistake that matters.

The card is the JSON document that tells an agent where your MCP server lives. Its schema is still a draft, so read Publish an MCP Server Card So Agents Can Find Your Tools for the fields. This post is only the Docusaurus mechanics for check P2, which AIScan grades.

Quick summary

Check first: run npx aiscan-cli yoursite.com and read check P2 in the Capabilities group.

Put the card in static/

Docusaurus copies the static/ directory into build/ unchanged, and the static assets docs describe that folder as the place for files served at the site root. A dot-prefixed folder is copied like any other. Create:

static/.well-known/mcp/server-card.json

{
  "serverInfo": { "name": "example-mcp", "version": "1.0.0" },
  "description": "Search the example catalog",
  "transport": { "type": "streamable-http", "url": "https://example.com/mcp" },
  "tools": [{ "name": "search", "description": "Search the catalog" }]
}

Replace the example values with your real server name, endpoint and tools. The field names follow the shape in AIScan's own P2 guidance and are a convention, not a ratified schema. Run npm run build. On 3.10.2 the output contained build/.well-known/mcp/server-card.json with no config change.

Do not put the card in src/pages/. That folder is for React and Markdown pages that become HTML routes, not for raw JSON files.

Keep it in a different folder

If your team keeps generated files out of static/, point Docusaurus at a second directory. The docs show staticDirectories: ['public', 'static'] in docusaurus.config.js:

export default {
  title: 'My site',
  staticDirectories: ['public', 'static'],
};

I put a card in public/.well-known/mcp/ and built. It landed at build/.well-known/mcp/server-card.json. Setting the option replaces the default list, so keep 'static' in it or your existing images and robots.txt disappear from the build.

GitHub Pages needs one more file

The Docusaurus docs warn that GitHub Pages runs published files through Jekyll, and that Jekyll discards files that begin with _. They recommend an empty .nojekyll file in your static directory. Add it now: static/.nojekyll. I did not deploy to GitHub Pages, so I cannot tell you what Jekyll does to a .well-known folder on your repository. After any Pages deploy, request the live URL instead of trusting the build folder.

Test with serve, not start

The two local servers disagree about missing files. I ran both against the same site:

The dev server answers an unknown path with the site's HTML shell and a 200, so a misspelled folder looks fine until you read the body. The production server returns a real 404. Build first, then check with npm run serve.

Verify the card

Run AIScan first:

npx aiscan-cli yoursite.com

Find P2 · MCP Server Card in the Capabilities group. It should pass. By hand, one request does the same job:

curl -si https://yoursite.com/.well-known/mcp/server-card.json

Expected output, trimmed:

HTTP/2 200
content-type: application/json

{"serverInfo":{"name":"example-mcp","version":"1.0.0"},...

Docusaurus sets no headers in a static build. The content-type your visitors see comes from the host in front of build/, and I did not test any host. Run the request on the domain agents will use.

When the card still fails

• 404 at the right path. The folder is static/well-known/ without the leading dot, or the build ran before you added the file. List build/.well-known/mcp/.
• 200 but the body is HTML. Your host rewrites unknown paths to index.html, the same thing docusaurus start does. Check content-type and the first bytes, never only the status.
• The card is missing after you set staticDirectories. The file sits in a folder you did not list, or you dropped 'static' from the array.
• It works locally and 404s on GitHub Pages. Add static/.nojekyll, redeploy and request the live URL.

Where to go next

Run npx aiscan-cli yoursite.com, confirm check P2, then browse the other fixes in the AIScan guides. The capabilities checks reference lists P1 to P4 and E2. If you also need llms.txt on Docusaurus, the llms.txt guide for Docusaurus covers it, and the Docusaurus setup guide covers the wider checklist. The Hugo version of this guide covers the same check on another static generator.