contextual

This MCP server provides Retrieval-Augmented Generation (RAG) capabilities by bridging MCP clients (such as Cursor IDE or Claude Desktop) with Contextual AI’s RAG agent. The server routes queries from your MCP client to a dedicated Contextual AI agent, retrieves relevant documentation from your knowledge base, and returns answers that are grounded in sources with citations. It’s designed to be flexible: you can customize the exposed tools and configure how queries are processed and retrieved, enabling precise control over what capabilities are available to MCP clients.

Using the server, you can leverage the Contextual AI Python SDK to perform queries against your agent. Typical workflows involve sending a natural language question, letting the MCP layer decide when to route the query to the Contextual AI agent, and then receiving a response that includes source references and citations. The server supports maintaining conversational context, providing source-attributed answers, and updating retrieval settings as needed. Integration with Cursor IDE and Claude Desktop enables seamless access to these capabilities from your preferred MCP clients.

Prerequisites:

• Python 3.10 or higher
• Access to an MCP-compatible environment (Cursor IDE and/or Claude Desktop)
• Contextual AI API key and Agent ID

Installation steps:

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 the package in editable mode (assuming a Python package setup is present): pip install -e .

4. Create a .env file (optional but recommended) to store sensitive keys: cat > .env << EOF API_KEY=your-contextual-ai-api-key AGENT_ID=your-contextual-ai-agent-id EOF

5. Ensure dependencies are installed and that uv (or your preferred transport) is available as configured in mcp.json. If you’re using uv for dependency management, install it as described in your environment and verify the path used in mcp.json.

6. Configure and start the MCP server as described in your environment (Cursor/Claude Desktop) using the mcp.json configuration file you created.

Tips and considerations:

• Environment variables: API_KEY and AGENT_ID are required for authenticating with Contextual AI. You can store them in a .env file for convenience.
• If you customize the server’s tools, maintain clear, domain-specific docstrings for each tool to help MCP clients route questions correctly.
• The server relies on the Contextual AI SDK; keep API usage within the provider’s quotas and rate limits.
• For local development, ensure the MCP client’s configuration path matches the location you placed mcp.json (project-specific or global as appropriate).
• If you encounter transport-related issues, verify that the chosen transport (e.g., stdio via uv) is supported in your development environment and that the server can access the necessary network resources for Contextual AI.
• You can extend capabilities by adding new tools with appropriate decorators and type hints in your server code, then updating the MCP client configuration accordingly.