Contextual AI MCP server

This Python-based MCP server provides a powerful way to add RAG (Retrieval-Augmented Generation) capabilities to development environments by connecting AI interfaces like Cursor IDE and Claude Desktop to a specialized Contextual AI agent.

Prerequisites

• Python 3.10 or higher
• Cursor IDE and/or Claude Desktop
• Contextual AI API key
• MCP-compatible environment

Installation

1. Clone the repository:

   git clone https://github.com/ContextualAI/contextual-mcp-server.git
   cd contextual-mcp-server
   

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
   

3. Install dependencies:

   pip install -e .
   

Configuration

Set Up Your MCP Server

The server requires some configuration before use, particularly for the single_agent server.

1. Customize the docstring for your RAG Agent to help MCP clients understand when to route questions to your agent. For example:

   A research tool focused on financial data on the largest US firms
   

   or

   A research tool focused on technical documents for Omaha semiconductors
   

2. Configure your Contextual AI credentials by setting these values:

   • API_KEY: Your Contextual AI API key
   • AGENT_ID: Your Contextual AI agent ID

   You can store these in an .env file:

   cat > .env << EOF
   API_KEY=key...
   AGENT_ID=...
   EOF
   

Connect to AI Interfaces

To integrate with Cursor IDE or Claude Desktop:

1. Find the path to your uv installation:

   UV_PATH=$(which uv)
   echo $UV_PATH
   # Example output: /Users/username/miniconda3/bin/uv
   

2. Create an MCP configuration file:

   cat > mcp.json << EOF
   {
    "mcpServers": {
      "ContextualAI-TechDocs": {
        "command": "$UV_PATH",
        "args": [
          "--directory",
          "\${workspaceFolder}",
          "run",
          "multi-agent/server.py"
        ]
      }
    }
   }
   EOF
   

3. Move this file to the appropriate location:

   mkdir -p .cursor/
   mv mcp.json .cursor/
   

   Configuration locations:

   • For Cursor: .cursor/mcp.json in your project directory or ~/.cursor/mcp.json for global access
   • For Claude Desktop: Use the same format in the Claude Desktop configuration directory

Usage

The MCP server provides access to Contextual AI's RAG capabilities from compatible clients like Cursor IDE and Claude Desktop.

How It Works

When you ask a question in your AI interface:

1. The MCP client determines if the question should be routed to your MCP server
2. Your server sends the query to the Contextual AI agent
3. The agent retrieves relevant documentation and generates a response with citations
4. The formatted answer is returned to your AI interface

Example Interaction

In Cursor IDE or Claude Desktop, you might ask:

Show me the code for initiating the RF345 microchip?

The system will route this question through your MCP server to the Contextual AI agent, which will search your documentation and provide a detailed, cited response.

Key Benefits

• Grounded Responses: Answers are based on your actual documentation
• Source Citations: Every response includes references to source documents
• Conversation Awareness: The system maintains context for follow-up questions
• Always Updated: Responses reflect the latest information in your knowledge base

For complete details on Contextual AI capabilities, check the official documentation.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "ContextualAI-TechDocs" '{"command":"$UV_PATH","args":["--directory","${workspaceFolder}","run","multi-agent/server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "ContextualAI-TechDocs": {
            "command": "$UV_PATH",
            "args": [
                "--directory",
                "${workspaceFolder}",
                "run",
                "multi-agent/server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "ContextualAI-TechDocs": {
            "command": "$UV_PATH",
            "args": [
                "--directory",
                "${workspaceFolder}",
                "run",
                "multi-agent/server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect