---
title: "How to publish /.well-known/mcp/server-card.json on Docusaurus"
slug: mcp-server-card-docusaurus
published: 2026-10-09T13:19:50.621668+00:00
updated: 2026-10-09T13:19:50.621668+00:00
author: "AIScan Content Team"
author_url: https://aiscan.site/about
category: "AI Readiness"
tags: MCP, server card, Docusaurus, well-known, check:P2, platform:docusaurus
description: "Publish /.well-known/mcp/server-card.json on Docusaurus: one file in static/, the staticDirectories option, the GitHub Pages catch, and why start lies."
url: https://aiscan.site/blog/mcp-server-card-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](https://aiscan.site/blog/publish-mcp-server-card) for the fields. This post is only the Docusaurus mechanics for check P2, which [AIScan grades](https://aiscan.site/).

## Quick summary

| If you want... | Do this | Time |
|---|---|---|
| The card live on Docusaurus | Create `static/.well-known/mcp/server-card.json` and rebuild | 5 min |
| To keep the card outside `static/` | Add the folder to `staticDirectories` in the config | 5 min |
| To host on GitHub Pages | Also add an empty `static/.nojekyll` | 1 min |
| To test it honestly | Use `docusaurus serve`, never `docusaurus start` | 2 min |

**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](https://docusaurus.io/docs/static-assets) 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**

```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`:

```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:

| Request | `docusaurus start` (port 3112) | `docusaurus serve` (port 3111) |
|---|---|---|
| `/.well-known/mcp/server-card.json` | 200, `application/json` | 200, `application/json; charset=utf-8` |
| `/.well-known/mcp/server-carb.json` (typo) | 200 | 404 |
| `/.well-known/mcp/server-card` | 200, `text/html` | 404 |

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:

```bash
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:

```bash
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](https://aiscan.site/guides). The [capabilities checks reference](https://aiscan.site/docs/checks/capabilities) lists P1 to P4 and E2. If you also need llms.txt on Docusaurus, [the llms.txt guide for Docusaurus](https://aiscan.site/blog/llms-txt-docusaurus) covers it, and the [Docusaurus setup guide](https://aiscan.site/blog/ai-readiness-setup-docusaurus) covers the wider checklist. The [Hugo version of this guide](https://aiscan.site/blog/mcp-server-card-hugo) covers the same check on another static generator.