CerevoxAI/cerevox-mcp-server

Cerevox MCP Server

Model Context Protocol (MCP) server for Cerevox AI - The Data Layer for AI Agents.

This MCP server exposes the full Cerevox API suite through the Model Context Protocol, enabling AI agents to:

• Parse documents with industry-leading accuracy (Lexa API)
• Search and query document collections with RAG (Hippo API)
• Manage accounts and users (Account API)

Features

Lexa - Document Parsing

• Parse documents from URLs with AI-powered extraction
• Support for PDF, DOCX, TXT, HTML, and 12+ formats
• Extract text, tables, images, and metadata
• Monitor processing jobs in real-time

Hippo - RAG & Semantic Search

• Create and manage document folders
• Upload files from URLs for processing
• Create chat sessions for Q&A
• Ask questions with AI-powered answers and source citations
• Retrieve conversation history
• Manage files and folders

Account - User Management

• Get account information and usage metrics
• View plan details and limits
• List and manage users
• Track API usage and billing

Installation

Prerequisites

• Python 3.9 or higher
• Cerevox API key (get one here)

Install from source

# Clone the repository
git clone https://github.com/CerevoxAI/cerevox-mcp-server.git
cd cerevox-mcp-server

# Install in development mode
pip install -e .

Install from PyPI (coming soon)

pip install cerevox-mcp-server

Configuration

Set up your API key

The server requires a Cerevox API key. Set it as an environment variable:

export CEREVOX_API_KEY="your-api-key-here"

Or add it to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

echo 'export CEREVOX_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Configure with Claude Desktop

Add this to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "cerevox": {
      "command": "python",
      "args": ["-m", "cerevox_mcp_server"],
      "env": {
        "CEREVOX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configure with other MCP clients

For other MCP clients, refer to their documentation for connecting to MCP servers. Generally, you'll need to:

1. Point the client to the server: python -m cerevox_mcp_server
2. Ensure the CEREVOX_API_KEY environment variable is set

Usage Examples

Document Parsing with Lexa

Parse a document and extract structured content:

Use the lexa_parse_document tool to parse this PDF: https://example.com/document.pdf

The AI will extract text, tables, and metadata from the document.

RAG Search with Hippo

Create a folder, upload documents, and ask questions:

1. Create a folder called "research_papers" with ID "research"
2. Upload this file: https://arxiv.org/pdf/2301.00001.pdf
3. Create a chat session for the "research" folder
4. Ask: "What are the main findings of this paper?"

The AI will:

1. Create the folder
2. Upload and process the document
3. Create a chat session
4. Answer your question using RAG with source citations

Account Management

Check your account usage:

1. Get my account information
2. Show my usage metrics
3. List all users in the account

Available Tools

Lexa Tools

Hippo Folder Tools

Hippo File Tools

Hippo Chat/Q&A Tools

Account Tools

Development

Setup development environment

# Clone and install with dev dependencies
git clone https://github.com/CerevoxAI/cerevox-mcp-server.git
cd cerevox-mcp-server
pip install -e ".[dev]"

Run tests

pytest

Code formatting

black src/

Type checking

mypy src/

Architecture

The server is built on:

• MCP Python SDK - Model Context Protocol implementation
• cerevox-python - Official Cerevox Python SDK
• AsyncIO - Asynchronous operations for optimal performance

Tool Design

Each tool follows a consistent pattern:

1. Input validation - Validates required parameters
2. Client initialization - Reuses authenticated clients
3. API call - Executes the Cerevox API operation
4. Response formatting - Returns structured JSON responses
5. Error handling - Provides clear error messages

Authentication

The server handles authentication automatically:

• API key loaded from CEREVOX_API_KEY environment variable
• Clients initialized lazily on first use
• Sessions maintained for optimal performance
• Automatic token refresh handled by cerevox-python SDK

Troubleshooting

"CEREVOX_API_KEY environment variable not set"

Make sure you've set the environment variable:

export CEREVOX_API_KEY="your-api-key-here"

"Connection refused" or "Server not responding"

Ensure the MCP server is running and your client is configured correctly. Check logs for detailed error messages.

"Authentication failed"

Verify your API key is valid and has the necessary permissions. Get a new key at https://cerevox.ai

Document parsing is slow

Large documents may take several minutes to process. Use the lexa_get_job_status tool to monitor progress.

Examples

Complete RAG Workflow

# This would be done through an MCP client like Claude Desktop

# 1. Create a folder for your documents
"Create a Hippo folder with ID 'my_docs' and name 'My Documents'"

# 2. Upload documents
"Upload https://example.com/report.pdf to the 'my_docs' folder"

# 3. Wait for processing (check file status)
"List files in the 'my_docs' folder to check processing status"

# 4. Create a chat session
"Create a chat session for the 'my_docs' folder"

# 5. Ask questions
"Ask in chat [chat_id]: What are the key recommendations in the report?"

# 6. Follow-up questions
"Ask in chat [chat_id]: Can you elaborate on the financial projections?"

# 7. Get conversation history
"Show me the conversation history for chat [chat_id]"

Document Analysis

# Parse a document and analyze its content
"Parse this document: https://example.com/contract.pdf using advanced mode"

# The response will include:
# - Extracted text content
# - Number of pages
# - Number of tables found
# - Content preview

Account Monitoring

# Check account status and usage
"Get my account information"
"Show my usage metrics"
"What's my current plan and its limits?"

Support

• Documentation: https://docs.cerevox.ai
• GitHub Issues: https://github.com/CerevoxAI/cerevox-mcp-server/issues
• Discord: https://discord.gg/cerevox
• Email: support@cerevox.ai

Contributing

We welcome contributions! Please see our for details.

License

This project is licensed under the MIT License - see the file for details.

Links

• Cerevox AI
• Cerevox Python SDK
• Model Context Protocol
• MCP Python SDK

Made with ❤️ by the Cerevox team

Happy Building! 🔍 🦛 ✨