Troubleshooting deployments
Start with the status check, curl https://docs.example.com/mcp. What it returns tells you which section below applies.
/mcp returns 404, or your site's 404 page
Cause: The platform isn't routing /mcp to the function.
Fix: Check the routing for your platform:
- Vercel: check the
rewritesentry invercel.json, and that the function is atapi/mcp.mjsin the project's root directory./api/mcpshould answer even without the rewrite. - Netlify: check
export const config = { path: '/mcp' }in the function, and that the function is innetlify/functions/. - Cloudflare Workers: check that
run_worker_firstincludes"/mcp". - Node: check the handler is mounted with
app.all('/mcp', …).
curl https://docs.example.com/mcp returns the status JSON.
Docs pages return 404, but the homepage and /mcp work
Cause: With trailingSlash: false, Docusaurus writes /docs/intro as docs/intro.html, and the host has to map the URL to that file.
Fix:
- Vercel: add
"cleanUrls": truetovercel.json. - Express: pass
{ extensions: ['html'] }toexpress.static. - Deno: retry with
.html, as the Deno example does.
A docs page, such as /docs/intro, loads.
The function build fails with "Cannot find module '…/build/mcp/bundle.json'"
Cause: The function was bundled before docusaurus build ran, or from a different directory.
Fix:
- Make sure the platform's build command runs
docusaurus build(usuallynpm run build). - Check the relative path from the function file to
build/mcp/bundle.json:../build/…fromapi/,../../build/…fromnetlify/functions/,./build/…from the site root. - If you changed the plugin's
outputDir, import from that directory instead ofbuild/mcp.
The deploy finishes, and build/mcp/bundle.json exists after npm run build.
ERR_IMPORT_ATTRIBUTE_MISSING, or "needs an import attribute of type: json"
Cause: Node.js and Deno need an import attribute to import JSON.
Fix: Write the import as:
import bundle from '../build/mcp/bundle.json' with { type: 'json' };
SyntaxError: Cannot use import statement outside a module
Cause: The function file is being run as CommonJS.
Fix: Name it .mjs, or set "type": "module" in package.json.
The status check returns 500 with an error message
Cause: The server started but couldn't load the bundle. The message says why and how to fix it.
Fix: Common ones:
- The bundle was built by a newer or older plugin version. Rebuild with the plugin version the function runs, and redeploy both together.
- The search index is missing. The
localindexer was turned off (indexers: false) but the server uses the built-in search. Turn the indexer back on or pass a custom search provider.
Other failures return Internal server error, and the details go to the platform's function logs.
The status check returns 200 with "initialized": true.
Escalate if: the message isn't one of these, or the error persists after a rebuild and redeploy. Run npx docusaurus-mcp-verify against the build and open an issue with its output and the status check's.
Tool calls return 406 Not Acceptable
Cause: The request's Accept header must include both application/json and text/event-stream. MCP clients send it; a hand-written request may not.
Fix: Add -H "Accept: application/json, text/event-stream" to curl requests.
Tool calls return 405 Method Not Allowed
Cause: MCP requests are POST. GET is the status check, and other methods get 405.
Fix: Send tool calls as POST.
Results link to localhost, example.com, or the wrong domain
Cause: Page URLs come from url in docusaurus.config.js at build time.
Fix: Fix url, rebuild, and redeploy. The baseUrl server option changes only what the status check reports.
docs_search results link to pages on the production domain.
The install button shows the wrong URL
Cause: The button advertises {url}/{outputDir}, which is /mcp by default.
Fix: If the endpoint is somewhere else, set server.url, or set server.urlBase: 'site' if the endpoint is under your baseUrl.
The install button shows the URL the status check answers at.
The endpoint serves old content
Cause: The bundle is baked into the function at deploy time, and the Node adapter reads it once at startup.
Fix: Redeploy after rebuilding. With the Node adapter, restart the process. Clients may cache list and read results for up to 5 minutes.
The status check's docCount matches what docusaurus-mcp-verify reports for the latest build.
A browser-based client is blocked by CORS
Cause: The handlers allow every origin by default, so a CORS error means corsOrigin is set and doesn't match.
Fix: Make sure corsOrigin matches the client's origin exactly, including the scheme and port.
Cloudflare: "Script startup exceeded CPU time limit" or "script too large"
Cause: The bundle is part of the Worker script, and the script is over your plan's limit.
Fix: Check the size with npx wrangler deploy --dry-run. If it's over your plan's limit, exclude pages you don't need agents to see (excludeRoutes), move to the Paid plan, or deploy the endpoint on a Node host instead.
npx wrangler deploy --dry-run reports a size under your plan's limit.
Still stuck
Run npx docusaurus-mcp-verify against your build. If the build verifies but the deployment fails, open an issue with the platform, the status check output, and the function logs.