Skip to main content

Deploy to Netlify

Netlify publishes build/ and runs the endpoint as a Netlify Function. The function declares its own path, so you don't need a redirect.

my-docs/
├── netlify/
│ └── functions/
│ └── mcp.mjs ← new: the MCP endpoint
├── docs/
├── docusaurus.config.js
├── netlify.toml ← new: build settings
└── package.json
Done when:

curl https://<your-domain>/mcp returns the status JSON with "initialized": true, a docCount above 0, and baseUrl on your production domain.

  • The plugin is set up: npm run build writes build/mcp/bundle.json. If not, follow Getting started first.
  • A Netlify account, and either the Netlify CLI (npx netlify) or access to the Netlify dashboard.

1. Add the function​

netlify/functions/mcp.mjs
import { createWebRequestHandler } from 'docusaurus-plugin-mcp-server/adapters';
import bundle from '../../build/mcp/bundle.json' with { type: 'json' };

const handler = createWebRequestHandler({ artifacts: bundle });

export default (request) => handler(request);

export const config = { path: '/mcp' };

config.path serves the function at /mcp instead of the default /.netlify/functions/mcp. The import goes up two directories, from netlify/functions/ to the site root.

Check:

netlify/functions/mcp.mjs exists, imports ../../build/mcp/bundle.json, and exports config with path: '/mcp'.

2. Add netlify.toml​

netlify.toml
[build]
command = "npm run build"
publish = "build"

[functions]
node_bundler = "esbuild"

Netlify runs command first and bundles functions afterward, so the bundle exists when the function is bundled. esbuild inlines the JSON into the function.

Check:

netlify.toml is next to docusaurus.config.js, with publish = "build".

3. Set your site URL​

Set url in docusaurus.config.js to your Netlify domain (https://my-docs.netlify.app) or your custom domain.

Check:

url in docusaurus.config.js is the production domain, not localhost or example.com.

4. Deploy​

Connect the repository in the Netlify dashboard (Add new project → Import an existing project). Netlify reads netlify.toml, so the build settings fill themselves in.

Or deploy with the Netlify CLI:

npx netlify deploy --build # draft deploy
npx netlify deploy --build --prod # production deploy
Check:

The deploy prints a deploy URL, and the deploy shows as Published in the Netlify dashboard.

5. Check it​

curl https://my-docs.netlify.app/mcp

You should get the status JSON. Then connect a client:

claude mcp add --transport http my-docs https://my-docs.netlify.app/mcp
Check:

curl https://my-docs.netlify.app/mcp (with your domain) returns JSON with "initialized": true and a docCount above 0.

Notes​

  • Deploy previews are built with your production url, so their tool results link to production. Netlify sets DEPLOY_PRIME_URL during builds. To make a preview link to itself, use it: url: process.env.CONTEXT === 'production' ? 'https://docs.example.com' : process.env.DEPLOY_PRIME_URL.
  • Release-only deploys. To deploy only on tags, turn off automatic builds (Project configuration → Build & deploy → Continuous deployment → Stop builds) and run netlify deploy --build --prod from a tag-triggered CI job, with NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID set as secrets.
  • Monorepos. Set Base directory to the site directory, and keep netlify.toml and netlify/functions/ there.

Something not working? See Troubleshooting.