A Model Context Protocol (MCP) server that provides RAG (Retrieval-Augmented Generation) capabilities using Contextual AI. This server integrates with a variety of MCP clients. In this documentation, we will show integration with the both Cursor IDE and Claude Desktop.

​
Overview

This MCP server acts as a bridge between AI interfaces (Cursor IDE or Claude Desktop) and a specialized Contextual AI agent. It enables:

  1. Query Processing: Direct your domain specific questions to a dedicated Contextual AI agent
  2. Intelligent Retrieval: Searches through comprehensive information in your knowledge base
  3. Context-Aware Responses: Generates answers that are:
  • Grounded in source documentation
  • Include citations and attributions
  • Maintain conversation context

​
Local MCP server

​
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
  1. Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
  1. Install dependencies:
pip install -e .

​
Configuration

​
Configure MCP Server

The server requires modifications of settings or use. For example, the single use server should be customized with an appropriate docstring for your RAG Agent.

The docstring for your query tool is critical as it helps the MCP client understand when to route questions to your RAG agent. Make it specific to your knowledge domain. Here is an example:

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

or

A research tool focused on technical documents for Omaha semiconductors

The server also requires the following settings from your RAG Agent:

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

If you’d like to store these files in .env file you can specify them like so:

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

​
AI Interface Integration

This MCP server can be integrated with a variety of clients. To use with either Cursor IDE or Claude Desktop create or modify the MCP configuration file in the appropriate location:

  1. First, find the path to your uv installation:
UV_PATH=$(which uv)
echo $UV_PATH
# Example output: /Users/username/miniconda3/bin/uv
  1. Create the configuration file using the full path from step 1:
cat > mcp.json << EOF
{
 "mcpServers": {
   "ContextualAI-TechDocs": {
     "command": "$UV_PATH", # make sure this is set properly
     "args": [
       "--directory",
       "\${workspaceFolder}",  # Will be replaced with your project path
       "run",
       "multi-agent/server.py"
     ]
   }
 }
}
EOF
  1. Move to the correct folder location, see below for options:
mkdir -p .cursor/
mv mcp.json .cursor/

Configuration locations:

  • For Cursor:
    • Project-specific: .cursor/mcp.json in your project directory
    • Global: ~/.cursor/mcp.json for system-wide access
  • For Claude Desktop:
    • Use the same configuration file format in the appropriate Claude Desktop configuration directory

​
Environment Setup

This project uses uv for dependency management, which provides faster and more reliable Python package installation.

​
Usage

The server provides Contextual AI RAG capabilities using the python SDK, which can available a variety of commands accessible from MCP clients, such as Cursor IDE and Claude Desktop.
The current server focuses on using the query command from the Contextual AI python SDK, however you could extend this to support other features such as listing all the agents, updating retrieval settings, updating prompts, extracting retrievals, or downloading metrics.

For example, in Cursor, you might ask:

Show me the code for initiating the RF345 microchip?

The MCP client will

  1. Determine if this should be routed to the MCP Server

Then the MCP server will

  1. Route the query to the Contextual AI agent
  2. Retrieve relevant documentation
  3. Generate a response with specific citations
  4. Return the formatted answer to Cursor

​
Remote MCP server

Cursor supports remote MCP servers via Server-Sent Events (SSE). This allows you to connect directly to hosted MCP services without local installation.

​
Configuration

  1. Create the MCP configuration file in one of these locations:
  • Project-specific: .cursor/mcp.json in your project directory
  • Global: ~/.cursor/mcp.json for system-wide access
  1. Add the configuration:
{
 "mcpServers": {
   "ContextualAI": {
     "type": "sse",
     "url": "https://mcp.app.contextual.ai/mcp/",
     "headers": {
       "Accept": "text/event-stream"
     }
   }
 }
}
  1. Restart Cursor IDE

​
Usage

​
Cursor IDE chat

In Cursor’s chat interface, you might ask:

Use RAG platform with api_key key-YOUR_API_KEY and agent_id YOUR_AGENT_ID, show me the code for initiating the RF345 microchip.

The MCP client will route the query to the Contextual AI agent and generate a response to Cursor.

​
Test script to check for connectivity

You may also run a short test script to verify the connection in Cursor (requires your Contextual AI API key and Agent ID):

#!/usr/bin/env python3
"""
Quick test script for ContextualAI HTTP MCP Server
Replace the following placeholders with your actual values:
- YOUR_API_KEY: Your Contextual AI API key
- YOUR_AGENT_ID: Your Contextual AI agent ID
- YOUR_QUERY: Your test question for the agent
"""

import asyncio
from fastmcp import Client

# Server configuration
SERVER_URL = "https://mcp.app.contextual.ai/mcp/"
API_KEY = "key-YOUR_API_KEY"

def extract_result(result):
   """Extract text from FastMCP result format"""
   if isinstance(result, list) and len(result) > 0:
       return result[0].text
   return str(result)

async def quick_test():
   """Quick test of essential functionality"""
   print("=== Quick ContextualAI HTTP MCP Test ===\n")
   
   try:
       # Use Streamable HTTP transport (the working one!)
       from fastmcp.client.transports import StreamableHttpTransport
       transport = StreamableHttpTransport(
           url=SERVER_URL,
           headers={
               "Authorization": f"Bearer {API_KEY}",
               "Content-Type": "application/json"
           }
       )
       
       async with Client(transport) as client:
           # Test 1: Server connection
           print("🔌 Testing server connection...")
           await client.ping()
           print("✅ Server is reachable")
           
           # Test 2: List tools
           tools = await client.list_tools()
           print(f"✅ Available tools: {[tool.name for tool in tools]}")
           
           # Test 3: Vegan diet query
           print("\n🔍 Testing query:")
           print("Query: 'YOUR_QUERY'")
           result = await client.call_tool("query", {
               "prompt": "YOUR_QUERY",
               "agent_id": "YOUR_AGENT_ID",
               "api_key": API_KEY
           })
           response = extract_result(result)
           print(f"Response: {response}")
           print("\n" + "="*80 + "\n")
           print("🎉 All tests completed successfully!")
           
   except Exception as e:
       print(f"❌ Test failed: {e}")
       print("Please check:")
       print("- Server URL is correct")
       print("- API key is valid")
       print("- Network connectivity")
       print("- FastMCP is installed: pip install fastmcp")

if __name__ == "__main__":
   asyncio.run(quick_test())

To run the test:

  1. Install FastMCP: pip install fastmcp
  2. Replace placeholders with your actual values
  3. Run: python test_script.py