@workos/mcp-docs-server

An MCP server that provides documentation, code examples, and changelogs for WorkOS SDKs and developer tooling.

Overview

This MCP server provides four main tools:

• Documentation: Access WorkOS SDK documentation
• Examples: Browse code examples and implementations
• Changelogs: View package changelogs and version history (includes RSS feed parsing)
• Search: Search all documentation for keywords or phrases (NEW)

The server works both inside the WorkOS monorepo (using local content) and externally (with fallback to hosted content). Changelog data is sourced from both traditional CHANGELOG.md files and the live WorkOS changelog RSS feed.

Installation

npm install @workos/mcp-docs-server

Usage

In Cursor/Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "workos": {
      "command": "npx",
      "args": ["@workos/mcp-docs-server"]
    }
  }
}

Programmatic Usage

import { getTools } from '@workos/mcp-docs-server/get-tools';

const tools = await getTools();
console.log(tools);

Development

Setup

npm install
npm run build

Prepare Content

Production Build (default - using latest WorkOS docs)

npm run build

This will:

1. Build the TypeScript code
2. Clone the latest WorkOS monorepo from GitHub
3. Extract documentation from packages/docs/content/
4. Extract examples and changelogs from the monorepo
5. Fetch and parse the latest changelog entries from the WorkOS RSS feed
6. Clean up the temporary clone

You can also run just the content preparation (pulls latest docs by default):

npm run prepare-content

Local Development (using local content)

For development when you want to use local content instead of cloning:

npm run build:dev

Or just prepare local content:

npm run prepare-content:local

This will organize content from local directories:

• Documentation from docs/ into .docs/organized/docs/
• Code examples from examples/ into .docs/organized/examples/
• Changelogs from packages/*/CHANGELOG.md into .docs/organized/changelogs/
• Note: RSS changelog parsing is skipped in local mode

Note: The default behavior requires access to the private WorkOS GitHub repository. Use the :local variants for development without repo access.

You can access the locally built MCP server by adding the build to your mcp.json.

{
  "mcpServers": {
    "workos": {
      "command": "node",
      "args": ["/path/to/dist/index.js"]
    }
  }
}

Publishing

For maintainers who need to build and publish new versions, see the Operator Guide for detailed instructions on:

• Prerequisites and required access
• Build process and expected output
• Publishing to npm
• Troubleshooting common issues

Available Tools

The MCP server provides a progressive discovery experience. Each tool supports browsing available content before accessing specific items.

workos_search (Recommended First Step)

Search all WorkOS documentation for keywords, phrases, error messages, or method names. This is the fastest way to find relevant documentation if you don't know the exact path or structure.

Parameters:

• query (string, required): The search term(s) to look for
• maxResults (number, optional): Maximum number of results to return (default: 10)

Example Usage:

// Find docs mentioning SAML errors
query: "invalid SAML response"

// Find docs about webhooks
query: "webhook"

// Find docs about a method
query: "createConnection"

How it works:

• Uses pure Node.js (no grep/execSync) to search all documentation files
• Returns snippets with line numbers and context
• Shows the document path for each match so you can use workos_docs to read the full content

workos_docs

Get WorkOS SDK documentation content by path. Use this when you know the documentation structure or want to browse hierarchically. If you don't know the exact path, use workos_search first to find relevant documents.

Parameters:

• path (string, required): Documentation path to retrieve. Use forward slashes to navigate folders. Examples: "sso/overview", "directory-sync/introduction", "user-management/authentication". Omit file extensions (.md, .mdx).

Example Usage:

// Read a specific document
path: "sso/overview"

Note: Zero-parameter discovery (listing all categories or directory contents) is not yet implemented. Use workos_search to find relevant paths.

workos_examples

Get WorkOS SDK code examples. Use this after checking documentation to find practical implementation examples.

Parameters:

• example (string, required): Example name or group to retrieve. Common groups: "sso", "directory-sync", "user-management", "audit-logs", "webhooks".

Example Usage:

// Get all examples in the SSO group
example: "sso"

workos_changelogs

Get WorkOS package changelogs to check version history, breaking changes, and new features. Useful for migration guides and understanding API evolution.

Parameters:

• package (string, required): Package name to get changelog for. Use "workos-platform" for general platform updates from the RSS feed, or specific packages like "@workos/node", "@workos/python", "@workos/ruby", "@workos/go", "@workos/php".

Example Usage:

// Get general platform changelog (from RSS feed)
package: "workos-platform"

// Get changelog for workos-node SDK
package: "@workos/node"

Data Sources:

• RSS Feed: The workos-platform package provides the latest platform updates, feature announcements, and product changes sourced from https://workos.com/changelog/rss.xml
• Markdown Files: SDK-specific packages provide traditional changelog data from CHANGELOG.md files in the monorepo

User Experience Design

This MCP server follows a progressive discovery pattern aligned with MCP best practices:

1. Search-first workflow: Use workos_search to find relevant documentation paths
2. Direct access: Use workos_docs, workos_examples, or workos_changelogs with the discovered path or name
3. Clear navigation hints: Each result includes hints for further exploration
4. Graceful fallbacks: When content isn't found, the server suggests similar options

This design allows AI assistants to efficiently explore available content without prior knowledge of the structure, making it easier to find relevant documentation, examples, or changelogs.

Architecture

File Structure

workos-docs-server/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── get-tools.ts      # Tool configuration
│   ├── prepare.ts        # Content preparation script
│   └── types.ts          # Type definitions
├── .docs/
│   └── organized/        # Processed content (generated)
│       ├── docs/
│       ├── examples/
│       └── changelogs/
├── package.json
├── tsup.config.ts
└── README.md

Runtime Behavior

1. prepare.ts (build step): Walks the monorepo and normalizes content into .docs/organized/
2. get-tools.ts: Checks for local organized content, falls back to remote URLs if missing
3. index.ts: Provides MCP-compliant server that serves the tools

License

MIT