coveo-mcp-server by coveo-labs - MCP Server

Coveo MCP Server

Disclaimer
The Coveo MCP Server is provided as-is, intended purely for educational and exploratory purposes. It’s not a production-ready product.

Overview

This is a simple MCP server that connects to Coveo and executes queries. It provides tools for:

Search functionality
Passage retrieval
Question answering

How It Works

The Coveo MCP Server acts as a bridge, exposing powerful Coveo APIs as simple, consumable tools for any MCP-compatible client, like Anthropic's Claude.

flowchart TD
    subgraph Your Application
        MCP_CLIENT["MCP Client (e.g., Claude)"]
    end
    
    subgraph This Project
        MCP_SERVER["Coveo MCP Server"]
    end

    subgraph Coveo Platform
        SEARCH_API["Search API"]
        PASSAGE_API["Passage Retrieval API"]
        ANSWER_API["Generative Answering API"]
    end

    MCP_CLIENT -- "Requests tools" --> MCP_SERVER
    MCP_SERVER -- "Calls API" --> SEARCH_API
    MCP_SERVER -- "Calls API" --> PASSAGE_API
    MCP_SERVER -- "Calls API" --> ANSWER_API

What You Can Build

By connecting your AI agents to Coveo's unified index, you can build powerful, secure, and accurate applications. For example:

A Customer Support Agent: An automated agent that answers customer questions using your official knowledge base and product documentation, complete with citations.
An Internal Knowledge Chatbot: A secure chatbot for employees to query internal resources like HR policies, technical documentation, or sales enablement materials, while respecting all user permissions.
A Commerce Copilot: An assistant that helps shoppers find the best product by understanding natural language queries and retrieving precise information from product catalogs.
A Research Assistant: An agent that can quickly summarize and synthesize information from a vast repository of documents by using passage_retrieval to gather context before generating a report.

Available Tools

Expose Coveo's powerful APIs as simple, easy-to-use tools for your agents.

🛠️ search_coveo

Use search_coveo to retrieve metadata, titles, or URLs. Ideal for broadly exploring information, navigating sources, or presenting lists of content.

Input:

query (string)
numberOfResults (int, optional, default: 5)

Output: JSON formatted search results or an error message.

🛠️ passage_retrieval

Use passage_retrieval to extract highly relevant text snippets. Useful for building answers, summaries, or new documents from source material.

Input:

query (string)
numberOfPassages (int, optional, default: 5)

Output: JSON formatted passages or an error message.

🛠️ answer_question

Use answer_question when you need a complete, consistent, and well-structured answer, powered by Coveo's Relevance Generative Answering engine.

Input:

query (string)

Output: A generated answer from Coveo sources with citations.

Get Started in 4 steps

Go from zero to a running Coveo MCP server in minutes.

1. Clone the Repository

Get the source code on your local machine.

git clone https://github.com/coveo-labs/coveo-mcp-server.git
cd coveo-mcp-server

2. Configure Your Environment

Copy the example environment file and add your Coveo API credentials.

cp .env.example .env

Then, edit the .env file with your credentials:

COVEO_API_KEY="<your-api-key>"
COVEO_ORGANIZATION_ID="<your-organization-id>"
COVEO_ANSWER_CONFIG_ID="<your-answer-config-id>"

3. Install Dependencies

We recommend using uv for fast dependency management.

# Install in editable mode with development dependencies
# Note the quotes around '.[dev]' to prevent shell errors
uv pip install -e '.[dev]'

4. Run the Server

Start the server. By default, it uses the modern streamable-http transport.

python -m coveo_mcp_server

The server will be available at http://127.0.0.1:8000.

Alternative Transport Options

The server supports multiple transport methods:

Streamable HTTP (Default): The new standard for MCP servers
```
python -m coveo_mcp_server
```
SSE Transport (Legacy): For older clients that require SSE
```
USE_SSE=true python -m coveo_mcp_server
```
STDIO Transport: For direct stdio communication
```
USE_STDIO=true python -m coveo_mcp_server
```

Core Features

Asynchronous by Design: Leverages httpx and asyncio for non-blocking API requests.
Grounded Generative Answering: Go beyond search results with AI-generated answers complete with citations from your indexed content.
Semantic Passage Retrieval: Intelligently extracts the most relevant text snippets, not just whole documents.
Easy Configuration: Simple setup using a .env file for your Coveo credentials.
Multiple Transports: Supports modern streamable-http, legacy SSE, and direct STDIO for maximum client compatibility.
Fully Tested: Includes a comprehensive test suite with pytest to ensure reliability.

Development & Testing

Development Setup

If you want to edit the source code or contribute to this project, set up a local development environment.

Create and Activate a Virtual Environment

First, create a virtual environment in the project's root directory. This will keep all the necessary dependencies isolated.

# Create the virtual environment
python -m venv .venv

# Activate it (macOS/Linux)
source .venv/bin/activate

# Or activate it (Windows)
# .\.venv\Scripts\activate

Install Dependencies

With the virtual environment active, install the project in "editable" mode. This allows you to make changes to the code and have them immediately reflected without reinstalling.
```
# Install in editable mode with development dependencies
# Note the quotes around '.[dev]' to prevent shell errors
uv pip install -e '.[dev]'
```
This command installs the package in editable mode (-e) and includes the extra development dependencies ([dev]), such as pytest, which are defined in the pyproject.toml file.

Testing Your Server

Testing with MCP Inspector

You can test the server with the MCP Inspector in two ways:

Using the mcp dev command:

mcp dev src/coveo_mcp_server/__main__.py

This will start the MCP Inspector at http://localhost:5173, where you can interact with and test the server's functionality.

Using npx with the MCP Inspector:

npx @modelcontextprotocol/inspector \
  uv \
  --directory /[path to project]/coveo-mcp-server \
  run \
  --with mcp \
  mcp run src/coveo_mcp_server/__main__.py

Testing your server with Claude for Desktop

First, make sure you have Claude for Desktop installed. You can install the latest version here. If you already have Claude for Desktop, make sure it's updated to the latest version.

We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at ~/Library/Application Support/Claude/claude_desktop_config.json in a text editor. Make sure to create the file if it doesn't exist.

Here's an example configuration:

{
    "mcpServers": {
        "coveo_mcp_server": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/coveo-mcp-server/src/coveo_mcp_server",
                "run",
                "__main__.py"
            ]
        }
    }
}

Note: If Claude for Desktop cannot find the uv command, you may need to specify the full path in the configuration:

"command": "/opt/homebrew/bin/uv"

Running the Test Suite

This project includes comprehensive unit tests.

Running All Tests

To run the tests and generate a coverage report:

./run_tests.sh

Or use pytest directly:

pytest tests/ -v --cov=src/coveo_mcp_server

Testing Transport Modes

To verify all transport modes are working correctly:

python test_transports.py

This script will verify that:

Streamable-HTTP transport starts correctly (default)
SSE transport starts correctly (legacy)
STDIO transport can be imported and initialized