Skip to main content
OwnDocs

MCP Server Integration

3 min readStableIntermediate

OwnDocs ships a built-in Model Context Protocol (MCP) server that exposes your documentation to AI tools. Any MCP-compatible client — Claude Desktop, Cursor, Windsurf, and others — can search your docs and fetch page content using your own documentation URL.

Stateless Spec 2026-07-28 Bearer auth

The server is a single stateless HTTP endpoint. Every request is independent and carries its own protocol metadata — there is no session, cookie, or handshake to configure or maintain.

What you can do

The server exposes two tools. Pick the one that fits the task.

search_docs

Free-text search across every documentation page. Returns matching pages with a title, URL, and snippet.

querylimit (optional)

fetch_page

Fetch the raw MDX content of a single page by its URL path, so an AI tool can read the full source.

url

Setup

Follow these three steps to connect a client. The same steps work on any domain and hosting provider — you only change your own URL and token.

  1. Enable the server

    The endpoint is opt-in so private documentation stays protected.

    • Public mode (ACCESS_MODE=public): always available. Set a token only if you want to require one.
    • Private mode (default): set both environment variables.
    Bash
    Bash
    MCP_ENABLED=true
MCP_BEARER_TOKEN=your-long-random-token

  2. Generate a token

    Run the following and store the output as a secret in your hosting platform.

    Bash
    Bash
    openssl rand -hex 32

    Treat this token as a secret. Anyone with it can read every page reachable through the server, so rotate it whenever a client loses access.

  3. Find your endpoint URL

    Your MCP endpoint is your documentation origin plus /api/mcp.

    Plain Text
    Plain Text
    https://docs.example.com/api/mcp

Connect your client

Add your endpoint URL and token to your client's MCP server configuration. The value of type is always http, and the token is always sent in the Authorization header.

Claude Desktop

Claude Desktop
JSON
{
  "mcpServers": {
    "owndocs": {
      "transport": {
        "type": "http",
        "url": "https://docs.example.com/api/mcp",
        "headers": {
          "Authorization": "Bearer your-long-random-token"
        }
      }
    }
  }
}

Cursor

In Cursor's MCP settings, add a remote HTTP server with these fields:

  • Type — HTTP
  • URL — https://docs.example.com/api/mcp
  • Authorization header — Bearer your-long-random-token

Windsurf

Windsurf
JSON
{
  "mcpServers": {
    "owndocs": {
      "url": "https://docs.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer your-long-random-token"
      }
    }
  }
}

Generic client

Any MCP-compatible client uses the same two values:

Plain Text
Plain Text
Endpoint: https://docs.example.com/api/mcp
Authorization header: Bearer your-long-random-token

Tool reference

search_docs

Searches every documentation page for the given query and returns the best matches.

querystringbodyrequired

Free-text search query. Non-empty string.

limitnumberbodyDefault: 5

Maximum number of results to return. Clamped between 1 and 20.

resultsarrayrequired

Array of matching pages, each with title, url, and snippet.

fetch_page

Fetches the raw MDX content of a single documentation page.

urlstringbodyrequired

Page path starting with / or relative. Path traversal is rejected.

contentstringrequired

The raw MDX content of the page, wrapped with the resolved url.

Verify the connection

Once connected, ask the client to list tools. It should show search_docs and fetch_page. Then ask it to search your documentation — if it returns matching pages, the integration is working.

Troubleshooting

The server is not enabled. In private mode, set both MCP_ENABLED=true and MCP_BEARER_TOKEN.

The token is missing or wrong. Confirm the Authorization: Bearer <token> header is set on every request.

Confirm the client points at the full endpoint URL (https://your-domain.com/api/mcp) and not just the domain.

The stateless MCP server uses POST only. There is no GET discovery endpoint, no session cookie, and no SSE upgrade to configure.

Related pages

Feature Catalog

Was this page helpful?