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
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 buildwritesbuild/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
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.
netlify/functions/mcp.mjs exists, imports ../../build/mcp/bundle.json, and exports config with path: '/mcp'.
2. Add 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.
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.
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
Connecting the repository happens in the dashboard, and the first CLI deploy asks the user to log in and pick a project. Ask the user to do either, and wait for the deploy URL. --prod replaces the live site.
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
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 setsDEPLOY_PRIME_URLduring 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 --prodfrom a tag-triggered CI job, withNETLIFY_AUTH_TOKENandNETLIFY_SITE_IDset as secrets. - Monorepos. Set Base directory to the site directory, and keep
netlify.tomlandnetlify/functions/there.
Something not working? See Troubleshooting.