Skip to main content

API

The package is ESM-only and has four entry points:

ImportUse it forRuns on
docusaurus-plugin-mcp-serverThe Docusaurus plugin, the server class, providers, utilitiesNode (build time)
docusaurus-plugin-mcp-server/adapterscreateWebRequestHandler for serverless and edge runtimesAny web-standard runtime. Imports no Node built-ins
docusaurus-plugin-mcp-server/adapters/nodeThe Node server and handler, reading the bundle from diskNode
docusaurus-plugin-mcp-server/themeThe install button, ForAgents/ForHumans, the agent guide components, and registry helpersThe 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';
  • evaluateSearch is documented in Measuring search quality.
  • GuideValidationError (experimental) is what the build throws when agent guides fail the format's checks. Its problems array lists each one, naming its page.
  • ContentIndexer, SearchRanker, and SearchProvider are 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'
FieldTypeDescription
siteUrlstringDocusaurus siteConfig.url
baseUrlstringDocusaurus siteConfig.baseUrl
outputDirstringPlugin outputDir (default 'mcp')
server.urlstringExplicit endpoint. When set, urlBase is ignored
server.urlBaseServerUrlBase'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's context, Workers' env and ctx, or { waitUntil }. The first argument with a waitUntil method gets the promise that onEvent returns. Since 2.6.

  • createNodeServer(options) returns an http.Server ready to .listen(), for local development and simple hosting.

  • createNodeHandler(options) returns an (req, res) handler for http.createServer() and Connect-style frameworks such as Express. Mount it for all methods: GET is the status check and OPTIONS is the CORS preflight. If a body parser such as express.json() has already read the request, the handler uses its req.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 as artifacts to McpDocsServer, or as initData.bundle to 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.

  • McpInstallButton is the dropdown readers use to install the server in their AI tool. McpInstallCopyEvent is what its onCopy prop receives. See Install button.
  • ForAgents and ForHumans mark page content for one audience: agents get ForAgents content and not ForHumans content, and people see the opposite. See Writing for agents.
  • AgentGuide, DoneWhen, Prerequisites, Step, Check, and Symptom mark 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.
  • mdxComponents is the object of components the plugin adds to MDX, keyed by name. Spread it into a swizzled MDXComponents that you ejected.
  • useMcpRegistry() is a React hook that returns the MCP config registry from the plugin's global data, or undefined if the plugin isn't installed.
  • createDocsRegistry(config) creates a preconfigured MCPConfigRegistry for a docs server.
  • createDocsRegistryOptions(config) returns the registry options without creating the registry.
  • McpConfig is the type { serverUrl: string; serverName: string }.