API
The package is ESM-only and has four entry points:
| Import | Use it for | Runs on |
|---|---|---|
docusaurus-plugin-mcp-server | The Docusaurus plugin, the server class, providers, utilities | Node (build time) |
docusaurus-plugin-mcp-server/adapters | createWebRequestHandler for serverless and edge runtimes | Any web-standard runtime. Imports no Node built-ins |
docusaurus-plugin-mcp-server/adapters/node | The Node server and handler, reading the bundle from disk | Node |
docusaurus-plugin-mcp-server/theme | The install button, ForAgents/ForHumans, the agent guide components, and registry helpers | The browser (your Docusaurus theme) |
The ArtifactBundle type is exported from the main, adapters, and adapters/node entry points. So are McpDocsEvent and McpEventHandler, the types of the onEvent server option. The main and adapters entry points also export WaitUntil, the type of a platform's per-request waitUntil. The main entry point also exports the event's parts: McpDocsSearchEvent, McpDocsFetchEvent, McpToolCallEventBase, and McpClientInfo.
Main exports
import {
// Docusaurus plugin (also the default export)
mcpServerPlugin,
// MCP server class (advanced / custom runtimes)
McpDocsServer,
// Tool definitions
docsSearchTool,
docsFetchTool,
// Provider loaders (built-in 'local' or custom indexers/providers)
loadIndexer,
loadSearchProvider,
// The built-in local search, for passing an instance as `search`
LocalSearchIndexer,
LocalSearchProvider,
// Measure how well a search provider ranks the right pages (experimental)
evaluateSearch,
// Resolve the MCP endpoint URL the install button uses
resolveServerUrl,
// Package Agent Skills into a skills.json artifact outside the plugin (experimental)
buildSkillsArtifact,
// Default plugin options
DEFAULT_PLUGIN_OPTIONS,
} from 'docusaurus-plugin-mcp-server';
evaluateSearchis documented in Measuring search quality.GuideValidationError(experimental) is what the build throws when agent guides fail the format's checks. Itsproblemsarray lists each one, naming its page.ContentIndexer,SearchRanker, andSearchProviderare documented in Custom providers.
resolveServerUrl
Derives the public MCP endpoint URL, with the same logic the plugin uses for the install button and global data. Use it in custom theme UI that has to agree with the plugin. The ResolveServerUrlInput and ServerUrlBase types are exported too.
import { resolveServerUrl, type ResolveServerUrlInput } from 'docusaurus-plugin-mcp-server';
const serverUrl = resolveServerUrl({
siteUrl: 'https://docs.example.com',
baseUrl: '/docs/',
outputDir: 'mcp',
server: { urlBase: 'site' },
});
// → 'https://docs.example.com/docs/mcp'
| Field | Type | Description |
|---|---|---|
siteUrl | string | Docusaurus siteConfig.url |
baseUrl | string | Docusaurus siteConfig.baseUrl |
outputDir | string | Plugin outputDir (default 'mcp') |
server.url | string | Explicit endpoint. When set, urlBase is ignored |
server.urlBase | ServerUrlBase | 'origin' (default) → {siteUrl}/{outputDir}; 'site' → under baseUrl |
ServerUrlBase is 'origin' | 'site', matching the server.url / server.urlBase plugin options.
Adapter exports
import { createWebRequestHandler } from 'docusaurus-plugin-mcp-server/adapters';
import {
createNodeServer,
createNodeHandler,
readArtifactBundle,
} from 'docusaurus-plugin-mcp-server/adapters/node';
-
createWebRequestHandler(options)returns a web-standard(request, context?, executionContext?) => Promise<Response>handler. Pass{ artifacts }. See the deployment guides. After the request, the handler takes the platform's per-request context, as the platform passes it: Netlify'scontext, Workers'envandctx, or{ waitUntil }. The first argument with awaitUntilmethod gets the promise thatonEventreturns. Since 2.6. -
createNodeServer(options)returns anhttp.Serverready to.listen(), for local development and simple hosting. -
createNodeHandler(options)returns an(req, res)handler forhttp.createServer()and Connect-style frameworks such as Express. Mount it for all methods:GETis the status check andOPTIONSis the CORS preflight. If a body parser such asexpress.json()has already read the request, the handler uses itsreq.body:import express from 'express';import { createNodeHandler } from 'docusaurus-plugin-mcp-server/adapters/node';const app = express();app.use(express.json());app.all('/mcp', createNodeHandler({ artifactsDir: './build/mcp' }));app.listen(3456); -
readArtifactBundle(dir)reads and validates the artifact bundle in a build directory (bundle.json, or the 2.0/2.1 per-file layout). Pass the result asartifactstoMcpDocsServer, or asinitData.bundleto a search provider you drive yourself.
createWebRequestHandler, createNodeServer, and createNodeHandler take the server options.
Theme exports
import {
McpInstallButton,
type McpInstallButtonProps,
type McpInstallCopyEvent,
ForAgents,
ForHumans,
type AudienceProps,
AgentGuide,
DoneWhen,
Prerequisites,
Step,
Check,
Symptom,
mdxComponents,
useMcpRegistry,
createDocsRegistry,
createDocsRegistryOptions,
type McpConfig,
} from 'docusaurus-plugin-mcp-server/theme';
MDX pages don't need to import the components: the plugin adds them to your theme's MDX components (mdxComponents option). Import them in your own React components, or when the option is off.
McpInstallButtonis the dropdown readers use to install the server in their AI tool.McpInstallCopyEventis what itsonCopyprop receives. See Install button.ForAgentsandForHumansmark page content for one audience: agents getForAgentscontent and notForHumanscontent, and people see the opposite. See Writing for agents.AgentGuide,DoneWhen,Prerequisites,Step,Check, andSymptommark up a setup or troubleshooting procedure that the build compiles into an Agent Skill. Their props types (AgentGuideProps,StepProps,SymptomProps,GuidePartProps) are exported too. See Agent guides.mdxComponentsis the object of components the plugin adds to MDX, keyed by name. Spread it into a swizzledMDXComponentsthat you ejected.useMcpRegistry()is a React hook that returns the MCP config registry from the plugin's global data, orundefinedif the plugin isn't installed.createDocsRegistry(config)creates a preconfiguredMCPConfigRegistryfor a docs server.createDocsRegistryOptions(config)returns the registry options without creating the registry.McpConfigis the type{ serverUrl: string; serverName: string }.