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

# MCP server

> Expose Hadiq.io's search and knowledge to external AI tools like Cursor and Claude Desktop via the Model Context Protocol.

The Hadiq.io MCP server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), a standard that lets AI tools connect to external data sources and services. By pointing Cursor, Claude Desktop, or any other MCP-compatible tool at your Hadiq.io instance, you give it direct access to your team's indexed knowledge — documents, wikis, code, and more.

## What MCP provides

MCP defines a standard interface for AI assistants to discover and call tools. When you connect an external tool to the Hadiq.io MCP server, it gains three capabilities:

| Tool                       | What it does                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `search_indexed_documents` | Search your team's private knowledge base indexed in Hadiq.io, with optional filters by source type and date |
| `search_web`               | Search the public internet for current events and general knowledge                                          |
| `open_urls`                | Fetch the full text content of one or more URLs (useful for following up on web search results)              |

The server also exposes an `indexed_sources` resource that lists all connected sources (e.g. `confluence`, `github`, `google_drive`) so the AI tool can filter searches by source.

<Note>
  All access controls are enforced by Hadiq.io. The MCP server authenticates every request using your Hadiq.io API key or Personal Access Token, so users only see documents they already have permission to access.
</Note>

## Prerequisites

* A running Hadiq.io instance with the MCP server enabled (`MCP_SERVER_ENABLED=true`)
* An Hadiq.io API key or Personal Access Token

You can generate a Personal Access Token in Hadiq.io under your user settings. API keys can be created by an admin under **Admin → API Keys**.

## Enabling the MCP server

The MCP server runs as a separate process alongside the Hadiq.io API server. Enable it by setting the following environment variable:

```bash theme={null}
MCP_SERVER_ENABLED=true
```

By default, the MCP server listens on port `8090`. You can change this with `MCP_SERVER_PORT`.

**Verify it is running:**

```bash theme={null}
curl https://your-Hadiq.io-domain.com/mcp/health
```

Expected response:

```json theme={null}
{
  "status": "healthy",
  "service": "mcp_server"
}
```

## Authentication

All requests to the MCP server require a bearer token in the `Authorization` header. Use either:

* A **Personal Access Token (PAT)** — scoped to your own user account
* An **API Key** — can be scoped to a specific set of permissions

The MCP server validates the token against your Hadiq.io API server on every request. No token is stored by the MCP server itself.

## Configuring MCP clients

<Tabs>
  <Tab title="Cursor">
    Add Hadiq.io to your Cursor MCP configuration. Open or create `~/.cursor/mcp.json` (or the workspace-level `.cursor/mcp.json`):

    ```json ~/.cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "Hadiq.io": {
          "url": "https://your-Hadiq.io-domain.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_PAT_OR_API_KEY"
          }
        }
      }
    }
    ```

    Replace `your-Hadiq.io-domain.com` with your Hadiq.io instance URL, and `YOUR_PAT_OR_API_KEY` with your token.

    After saving, restart Cursor. Hadiq.io will appear in the MCP tools panel and Cursor will use it automatically when generating code or answering questions that benefit from your team's knowledge.

    <Tip>
      Cursor works best when you also tell it what sources are available. Ask it to list `indexed_sources` to see what Hadiq.io has indexed in your workspace.
    </Tip>
  </Tab>

  <Tab title="Claude Desktop">
    Add Hadiq.io to your Claude Desktop configuration file.

    **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

    **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "Hadiq.io": {
          "url": "https://your-Hadiq.io-domain.com/mcp",
          "transport": "http",
          "headers": {
            "Authorization": "Bearer YOUR_PAT_OR_API_KEY"
          }
        }
      }
    }
    ```

    Replace `your-Hadiq.io-domain.com` with your Hadiq.io instance URL, and `YOUR_PAT_OR_API_KEY` with your token.

    Restart Claude Desktop. You will see the Hadiq.io tools listed under the MCP tools icon in the chat interface.
  </Tab>

  <Tab title="Hadiq.io Cloud">
    If you are using Hadiq.io Cloud, use the cloud endpoint:

    ```json mcp.json theme={null}
    {
      "mcpServers": {
        "Hadiq.io": {
          "url": "https://cloud.Hadiq.io/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_PAT_OR_API_KEY"
          }
        }
      }
    }
    ```

    Generate your token from your Hadiq.io Cloud account settings.
  </Tab>

  <Tab title="Other MCP clients">
    Any MCP client that supports HTTP transport with custom headers can connect to Hadiq.io. Configure it with:

    * **URL:** `https://your-Hadiq.io-domain.com/mcp`
    * **Transport:** HTTP (streamable HTTP / HTTP POST)
    * **Authorization header:** `Bearer YOUR_PAT_OR_API_KEY`

    Refer to your client's documentation for the exact configuration format.
  </Tab>
</Tabs>

## Available tools

### `search_indexed_documents`

Searches your team's private knowledge base indexed in Hadiq.io.

| Parameter      | Type      | Description                                                                                                       |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `query`        | string    | The search query                                                                                                  |
| `source_types` | string\[] | Optional. Filter by source type (e.g. `"confluence"`, `"github"`). Use `indexed_sources` to see available values. |
| `time_cutoff`  | string    | Optional. ISO 8601 datetime. Exclude documents older than this date.                                              |
| `limit`        | integer   | Maximum number of results to return (default: 10)                                                                 |

Returns ranked document chunks with content, source type, link, and relevance score.

### `search_web`

Searches the public internet.

| Parameter | Type    | Description                            |
| --------- | ------- | -------------------------------------- |
| `query`   | string  | The search query                       |
| `limit`   | integer | Maximum number of results (default: 5) |

Returns titles, URLs, and snippets. Use `open_urls` to fetch full content.

### `open_urls`

Fetches the full text content of one or more URLs.

| Parameter | Type      | Description           |
| --------- | --------- | --------------------- |
| `urls`    | string\[] | List of URLs to fetch |

Returns the full text content and metadata for each URL.

## Environment variables

| Variable                  | Default | Description                                  |
| ------------------------- | ------- | -------------------------------------------- |
| `MCP_SERVER_ENABLED`      | `false` | Set to `true` to enable the MCP server       |
| `MCP_SERVER_PORT`         | `8090`  | Port the MCP server listens on               |
| `MCP_SERVER_CORS_ORIGINS` | —       | Comma-separated list of allowed CORS origins |

<Warning>
  The MCP server runs as a separate process. If you are self-hosting Hadiq.io, make sure port `8090` is accessible from the machines running your MCP clients, or configure a reverse proxy to expose it on a standard port.
</Warning>