MCP Server

Introduction

Connect AI assistants to your Guru’s knowledge base using the Model Context Protocol (MCP). 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 or self-hosted with Enterprise plan)
An API key from API Keys
An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

Getting Your API Key

Go to API Keys
Click “New API Key” to generate a new key
Copy the API key (it starts with gb-)

Store your API key securely. It provides access to your Guru and should not be shared publicly.

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.

For self-hosted Gurubase (Enterprise plan), use your instance URL: http://localhost:8029/mcp/{guru_slug}/

Authentication

Send your API key in either of these headers:

Authorization: Bearer YOUR_API_KEY (works with most MCP clients)
X-API-KEY: YOUR_API_KEY (recommended for VS Code Copilot and any client that intercepts the Authorization header)

VS Code Copilot users: use X-API-KEY. Copilot’s MCP client manages the Authorization header internally and does not always forward user-supplied values to the server, which can cause Authorization: Bearer to fail. X-API-KEY is a non-standard header name, so Copilot passes it through unchanged. The same workaround applies to other MCP clients that layer their own auth on top of MCP.

Client Setup

Replace {guru_slug} with your Guru’s slug and YOUR_API_KEY with your actual API key in the examples below.

Cursor

In Cursor, go to Settings > MCP Servers and add one of the following configurations:Remote Server Connection

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

Local Server Connection

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

Claude Code

Remote Server Connection

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

Local Server Connection

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"

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

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

Local Server Connection

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

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:

"env": {
  "PATH": "/opt/homebrew/opt/node@20/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}

Windsurf

Add to your Windsurf MCP config file (~/.codeium/windsurf/mcp_config.json):Remote Server Connection

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

Local Server Connection

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

VS Code (Copilot)

Add to your VS Code settings (settings.json):

Use the X-API-KEY header (not Authorization: Bearer) when configuring Copilot. Copilot’s MCP client intercepts the Authorization header, which causes authentication to fail.

Remote Server Connection

{
  "mcp": {
    "servers": {
      "gurubase-{guru_slug}": {
        "url": "https://api.gurubase.io/mcp/{guru_slug}/",
        "headers": {
          "X-API-KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Local Server Connection

{
  "mcp": {
    "servers": {
      "gurubase-{guru_slug}": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://api.gurubase.io/mcp/{guru_slug}/",
          "--header",
          "X-API-KEY: YOUR_API_KEY"
        ]
      }
    }
  }
}

Zed

Add to your Zed settings file (~/.config/zed/settings.json):Local Server Connection

{
  "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"
        ]
      }
    }
  }
}

Other MCP Clients

For any MCP-compatible client, use one of these configuration patterns:Remote Server Connection (if your client supports url + headers):

{
  "url": "https://api.gurubase.io/mcp/{guru_slug}/",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

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

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

Which one should I use? If your client supports url, use Remote. If it only supports command, use Local.

Authentication failing? If Authorization: Bearer YOUR_API_KEY doesn’t work, your client may be intercepting the Authorization header. Switch to X-API-KEY: YOUR_API_KEY. The Gurubase MCP endpoint accepts both.

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:

{
  "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

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.

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:

{
  "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:

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

Replace localhost:8029 with your actual Gurubase instance URL if different.

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.

Country detection caveat: Country is detected from the client’s IP address. Clients that connect directly to Gurubase (Claude Desktop, Claude Code via mcp-remote, Cursor, Windsurf, Zed) will resolve to the developer’s country. Clients that proxy MCP traffic through their own infrastructure (notably VS Code Copilot, which routes through GitHub-hosted servers) will resolve to the proxy’s region rather than the developer’s location.

Troubleshooting

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:

Find your npx location: which npx
Add the directory to the PATH in your config:

"env": {
  "PATH": "/opt/homebrew/opt/node@20/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}

Completely quit and restart Claude Desktop (Cmd+Q, not just close the window)

'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

'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

'Question was processed but could not be retrieved'

This is a temporary error. Try asking the question again. If it persists, contact support.

Tools not appearing in Claude

Verify your MCP configuration is correct
Restart Claude Desktop completely
Check Claude Desktop logs for connection errors
Test the endpoint manually:

curl -X POST https://api.gurubase.io/mcp/{guru_slug}/ \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Authorization: Bearer YOUR_API_KEY also works.

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.

API Reference

For programmatic access without MCP, see our REST API documentation.

Next Steps

MCP Client Connections

Connect external MCP servers to your Guru

API Reference

Explore our REST API documentation

Website Widget

Add your Guru to your website

Slack Bot

Connect your Guru to Slack

Discord Bot

Add your Guru to Discord

Get Started

Guides

Integrations

Advanced

Introduction

Prerequisites

Getting Your API Key

MCP Server URL

Authentication

Client Setup

Available Tools

gurubase_ask

gurubase_semantic_search

Example Usage

Self-Hosted Configuration

Analytics

Troubleshooting

API Reference

Next Steps

MCP Client Connections

API Reference

Website Widget

Slack Bot

Discord Bot

​Introduction

​Prerequisites

​Getting Your API Key

​MCP Server URL

​Authentication

​Client Setup

​Available Tools

​gurubase_ask

​gurubase_semantic_search

​Example Usage

​Self-Hosted Configuration

​Analytics

​Troubleshooting

​API Reference

​Next Steps

MCP Client Connections

API Reference

Website Widget

Slack Bot

Discord Bot

Introduction

Prerequisites

Getting Your API Key

MCP Server URL

Authentication

Client Setup

Available Tools

gurubase_ask

gurubase_semantic_search

Example Usage

Self-Hosted Configuration

Analytics

Troubleshooting

API Reference

Next Steps