> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gurubase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect your Guru to Claude Desktop, Claude Code, and other MCP clients

## Introduction

Connect AI assistants to your Guru's knowledge base using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Use your Guru directly within Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients.

With the MCP integration, you can:

* Ask questions and get AI-generated answers from your knowledge base
* Search for relevant documentation without generating an answer
* Access your Guru's knowledge directly in your development workflow

## Prerequisites

Before setting up the MCP integration, ensure you have:

* A Guru on Gurubase (either on [Gurubase Cloud](https://app.gurubase.io) or self-hosted with Enterprise plan)
* An API key from [API Keys](https://app.gurubase.io/api-keys)
* An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

## Getting Your API Key

1. Go to [API Keys](https://app.gurubase.io/api-keys)
2. Click **"New API Key"** to generate a new key
3. Copy the API key (it starts with `gb-`)

<Note type="warning">
  Store your API key securely. It provides access to your Guru and should not be
  shared publicly.
</Note>

## MCP Server URL

Your Guru's MCP server is available at:

```
https://api.gurubase.io/mcp/{guru_slug}/
```

Replace `{guru_slug}` with your Guru's slug. You can find the slug in your Guru's URL. For example, if your Guru is at `https://app.gurubase.io/g/kubernetes`, the slug is `kubernetes`.

<Note type="warning">
  For self-hosted Gurubase (Enterprise plan), use your instance URL:
  `http://localhost:8029/mcp/{guru_slug}/`
</Note>

## Client Setup

<Note>
  Replace `{guru_slug}` with your Guru's slug and `YOUR_API_KEY` with your
  actual API key in the examples below.
</Note>

<AccordionGroup>
  <Accordion title="Cursor">
    In Cursor, go to **Settings** > **MCP Servers** and add one of the following configurations:

    **Remote Server Connection**

    ```json theme={null}
    {
      "mcpServers": {
        "gurubase-{guru_slug}": {
          "url": "https://api.gurubase.io/mcp/{guru_slug}/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    **Local Server Connection**

    ```json theme={null}
    {
      "mcpServers": {
        "gurubase-{guru_slug}": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://api.gurubase.io/mcp/{guru_slug}/",
            "--header",
            "Authorization: Bearer YOUR_API_KEY"
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Claude Code">
    **Remote Server Connection**

    ```bash theme={null}
    claude mcp add --transport http \
      gurubase-{guru_slug} https://api.gurubase.io/mcp/{guru_slug}/ \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    **Local Server Connection**

    ```bash theme={null}
    claude mcp add gurubase-{guru_slug} -s user -- \
      npx -y mcp-remote "https://api.gurubase.io/mcp/{guru_slug}/" \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```
  </Accordion>

  <Accordion title="Claude Desktop">
    Edit your Claude Desktop configuration file:

    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

    **Remote Server Connection**

    ```json theme={null}
    {
      "mcpServers": {
        "gurubase-{guru_slug}": {
          "url": "https://api.gurubase.io/mcp/{guru_slug}/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    **Local Server Connection**

    ```json theme={null}
    {
      "mcpServers": {
        "gurubase-{guru_slug}": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://api.gurubase.io/mcp/{guru_slug}/",
            "--header",
            "Authorization: Bearer YOUR_API_KEY"
          ]
        }
      }
    }
    ```

    <Note>
      **macOS users:** If Claude Desktop can't find `npx`, run `which npx` in your terminal and add an `env` section with that directory in the PATH. For example, if `npx` is at `/opt/homebrew/opt/node@20/bin/npx`, add:

      ```json theme={null}
      "env": {
        "PATH": "/opt/homebrew/opt/node@20/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
      ```
    </Note>
  </Accordion>

  <Accordion title="Windsurf">
    Add to your Windsurf MCP config file (`~/.codeium/windsurf/mcp_config.json`):

    **Remote Server Connection**

    ```json theme={null}
    {
      "mcpServers": {
        "gurubase-{guru_slug}": {
          "url": "https://api.gurubase.io/mcp/{guru_slug}/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    **Local Server Connection**

    ```json theme={null}
    {
      "mcpServers": {
        "gurubase-{guru_slug}": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://api.gurubase.io/mcp/{guru_slug}/",
            "--header",
            "Authorization: Bearer YOUR_API_KEY"
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VS Code (Copilot)">
    Add to your VS Code settings (`settings.json`):

    **Remote Server Connection**

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "gurubase-{guru_slug}": {
            "url": "https://api.gurubase.io/mcp/{guru_slug}/",
            "headers": {
              "Authorization": "Bearer YOUR_API_KEY"
            }
          }
        }
      }
    }
    ```

    **Local Server Connection**

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "gurubase-{guru_slug}": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote",
              "https://api.gurubase.io/mcp/{guru_slug}/",
              "--header",
              "Authorization: Bearer YOUR_API_KEY"
            ]
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Zed">
    Add to your Zed settings file (`~/.config/zed/settings.json`):

    **Local Server Connection**

    ```json theme={null}
    {
      "context_servers": {
        "gurubase-{guru_slug}": {
          "command": {
            "path": "npx",
            "args": [
              "-y",
              "mcp-remote",
              "https://api.gurubase.io/mcp/{guru_slug}/",
              "--header",
              "Authorization: Bearer YOUR_API_KEY"
            ]
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Other MCP Clients">
    For any MCP-compatible client, use one of these configuration patterns:

    **Remote Server Connection** (if your client supports `url` + `headers`):

    ```json theme={null}
    {
      "url": "https://api.gurubase.io/mcp/{guru_slug}/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
    ```

    **Local Server Connection** (if your client only supports `command`):

    ```json theme={null}
    {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.gurubase.io/mcp/{guru_slug}/",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
    ```

    <Note>
      **Which one should I use?** If your client supports `url`, use **Remote**. If it only supports `command`, use **Local**.
    </Note>
  </Accordion>
</AccordionGroup>

## Available Tools

Once connected, your MCP client will have access to two tools:

### gurubase\_ask

Ask a question and get an AI-generated answer from your knowledge base.

**When to use:**

* You need a complete, synthesized answer
* You want explanations, tutorials, or how-to guidance
* Quality and completeness matter more than speed

**Parameters:**

| Name       | Type   | Required | Description                   |
| ---------- | ------ | -------- | ----------------------------- |
| `question` | string | Yes      | The question to ask your Guru |

**Response:**

```json theme={null}
{
  "content": "# How do I install Gurubase selfhosted version?\n\nGurubase **Self-Hosted Enterprise Edition** lets you deploy...",
  "slug": "install-gurubase-self-hosted-requirements-05d0f038",
  "trust_score": 35,
  "references": [
    {
      "title": "Self-Hosted Enterprise Edition - Onprem Deployment - Gurubase",
      "link": "https://docs.gurubase.ai/self-hosted",
      "icon": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3",
      "type": "WEBSITE"
    },
    {
      "title": "Getting Started with Gurubase - Help Center",
      "link": "https://support.gurubase.io/hc/en-us/articles/123456789",
      "icon": "https://support.gurubase.io/favicon.ico",
      "type": "ZENDESK"
    }
  ]
}
```

| Field         | Description                                            |
| ------------- | ------------------------------------------------------ |
| `content`     | The AI-generated answer in Markdown format             |
| `slug`        | Unique identifier for this Q\&A                        |
| `trust_score` | Confidence score (0-100) indicating answer reliability |
| `references`  | Array of source documents used to generate the answer  |

<Note>
  This tool is slower (typically 10-30 seconds) because it retrieves sources,
  synthesizes information, and generates a comprehensive answer. Use
  `gurubase_semantic_search` for quick lookups.
</Note>

### gurubase\_semantic\_search

Find relevant source documents without generating an answer.

**When to use:**

* You need a quick check of what documentation exists
* You want to find specific articles, guides, or references
* You need to explore the knowledge base
* Speed is important

**Parameters:**

| Name     | Type   | Required | Description                       |
| -------- | ------ | -------- | --------------------------------- |
| `query`  | string | Yes      | The search query                  |
| `labels` | array  | No       | Filter results by category labels |

**Response:**

```json theme={null}
{
  "sources": [
    {
      "title": "Widget Runtime Sequence",
      "link": "text-gurubase-growth-Widget_Runtime_Sequence-9a65cf78",
      "labels": [],
      "icon_url": "",
      "text": "sequenceDiagram\n  autonumber\n  participant U as User\n  participant B as Browser (your site)...",
      "type": "Text"
    },
    {
      "title": "Discord - Gurubase",
      "link": "https://docs.gurubase.ai/integrations/bots/discord",
      "labels": [],
      "icon_url": "",
      "text": "The image shows a Discord bot integration that is connected to a specific Discord server...",
      "type": "Text"
    },
    {
      "title": "README.md",
      "link": "https://github.com/Gurubase/gurubase-widget/tree/master/README.md",
      "labels": [],
      "icon_url": "",
      "text": "## Path-Based Widget Loading\n\nIf you want to load the widget only on specific paths...",
      "type": "Text"
    }
  ],
  "total_count": 15
}
```

| Field                | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `sources`            | Array of matching documents                             |
| `sources[].title`    | Document or page title                                  |
| `sources[].link`     | URL to the source (external link or internal reference) |
| `sources[].labels`   | Category labels associated with the source              |
| `sources[].icon_url` | Icon URL for the source                                 |
| `sources[].text`     | Relevant text snippet (truncated to \~500 chars)        |
| `sources[].type`     | Source type (e.g., "Text")                              |
| `total_count`        | Total number of sources returned                        |

## Example Usage

Once configured, you can use your Guru directly in Claude:

**Asking a question:**

> "Use the gurubase\_ask tool to explain how to set up authentication"

**Searching documentation:**

> "Use gurubase\_semantic\_search to find docs about rate limiting"

**With labels filter:**

> "Search for API documentation rate limiting using gurubase\_semantic\_search with labels 'api', 'reference"

## Self-Hosted Configuration

For self-hosted Gurubase (Enterprise plan), update the URL to point to your instance:

```json theme={null}
{
  "mcpServers": {
    "gurubase-{guru_slug}": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8029/mcp/{guru_slug}/",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
```

<Note type="warning">
  Replace `localhost:8029` with your actual Gurubase instance URL if different.
</Note>

## Analytics

Questions asked via MCP appear in your Guru's Analytics dashboard with the source type **"MCP"**. This allows you to track usage and identify common questions from your development team.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude Desktop: 'Failed to spawn process: No such file or directory'">
    This error occurs when Claude Desktop cannot find `npx` in its PATH. GUI applications on macOS don't inherit your shell's PATH.

    **Solution:** Add the `env` section with the correct PATH:

    1. Find your npx location: `which npx`
    2. Add the directory to the PATH in your config:

    ```json theme={null}
    "env": {
      "PATH": "/opt/homebrew/opt/node@20/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
    }
    ```

    3. Completely quit and restart Claude Desktop (Cmd+Q, not just close the window)
  </Accordion>

  <Accordion title="'Invalid API key' error">
    * Verify your API key is correct and starts with `gb-` - Check that the API
      key has not been revoked - Ensure the API is enabled for your Guru in Settings
  </Accordion>

  <Accordion title="'Guru not found' error">
    * Verify the guru\_slug in the URL matches your Guru's slug - Check that the
      Guru is not disabled - Ensure the API is enabled for your Guru
  </Accordion>

  <Accordion title="'Question was processed but could not be retrieved'">
    This is a temporary error. Try asking the question again. If it persists,
    contact support.
  </Accordion>

  <Accordion title="Tools not appearing in Claude">
    1. Verify your MCP configuration is correct
    2. Restart Claude Desktop completely
    3. Check Claude Desktop logs for connection errors
    4. Test the endpoint manually:

    ```bash theme={null}
    curl -X POST https://api.gurubase.io/mcp/{guru_slug}/ \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
    ```
  </Accordion>

  <Accordion title="Slow responses from gurubase_ask">
    The `gurubase_ask` tool generates comprehensive answers which takes time. For faster lookups, use `gurubase_semantic_search` to find relevant documents without AI synthesis.
  </Accordion>
</AccordionGroup>

## API Reference

For programmatic access without MCP, see our [REST API documentation](/api-reference/introduction).

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Client Connections" icon="plug" href="/guides/mcp-client">
    Connect external MCP servers to your Guru
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore our REST API documentation
  </Card>

  <Card title="Website Widget" icon="browser" href="/integrations/bots/website-widget">
    Add your Guru to your website
  </Card>

  <Card title="Slack Bot" icon="slack" href="/integrations/bots/slack">
    Connect your Guru to Slack
  </Card>

  <Card title="Discord Bot" icon="discord" href="/integrations/bots/discord">
    Add your Guru to Discord
  </Card>
</CardGroup>