---
layout: 'page'
uri: '/ai-integration/mcp-setup'
position: 1
slug: 'ai-integration-mcp-setup'
parent: 'ai-integration'
navTitle: 'MCP setup'
title: 'MCP setup'
description: 'How to connect Documan MCP server to AI coding tools like Claude Code, Cursor, Windsurf, and others.'
---

# MCP setup

Documan includes an MCP (Model Context Protocol) server that allows AI coding tools to search and read your documentation. The server is available at the same address as the web UI.


## MCP endpoint

Point your AI tools to your deployed Documan instance:

```
https://docs.yourdomain.com/mcp
```

Transport type: `http`

Any MCP-compatible tool can connect using this URL. The setup varies by tool — see examples below.

**Important:** Always connect to your production/staging Documan instance — not `localhost`. The MCP server should serve versioned, imported and vectorized documentation. Running MCP locally against unfinished work leads to inconsistent AI responses.


## Prerequisites

Your documentation must be imported and vectorized before MCP search works. This should be part of your build/deploy pipeline (see [Docker setup](/deployment/docker-setup)):

```bash
./documan import
./documan vectorize
```

`DOCUMAN_OPENAI_API_KEY` must be set both during `vectorize` and at runtime (`documan serve`). Each MCP search query calls OpenAI to convert the query text into an embedding for similarity matching. See [Semantic search](/configuration/semantic-search#documan-openai-api-key) for details.


## Claude Code CLI

Global configuration (available in all projects):

```bash
claude mcp add documan --transport http https://docs.yourdomain.com/mcp
```

Or create `.mcp.json` in your project root for local configuration:

```json
{
    "mcpServers": {
        "documan": {
            "type": "http",
            "url": "https://docs.yourdomain.com/mcp"
        }
    }
}
```


## Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
    "mcpServers": {
        "documan": {
            "type": "http",
            "url": "https://docs.yourdomain.com/mcp"
        }
    }
}
```


## Cursor, Windsurf, and others

Most MCP-compatible tools use the same JSON configuration format. Add the MCP server in your tool's settings or configuration file:

```json
{
    "mcpServers": {
        "documan": {
            "type": "http",
            "url": "https://docs.yourdomain.com/mcp"
        }
    }
}
```

Refer to your tool's documentation for the exact location of the MCP configuration file.


## Protecting the MCP endpoint

Documan doesn't support OAuth for MCP yet. You can protect the endpoint using a reverse proxy or basic auth.

### Custom headers (recommended)

Pass authentication headers in the MCP configuration. Example for Cloudflare Zero Trust:

```json
{
    "mcpServers": {
        "documan": {
            "type": "http",
            "url": "https://docs.yourdomain.com/mcp",
            "headers": {
                "CF-Access-Client-Id": "<your-client-id>.access",
                "CF-Access-Client-Secret": "<your-client-secret>"
            }
        }
    }
}
```

For Cloudflare, generate a service token under Access → Service Auth → Service Tokens. The same approach works for Nginx, Traefik, AWS ALB, or any proxy that requires custom headers.

### Basic auth

Include credentials directly in the URL:

```
https://user:password@docs.yourdomain.com/mcp
```

---

[← 🤖 AI integration](/ai-integration.md) | [AI coding skill →](/ai-integration/documan-skill.md)