Cerevox 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

Tool	Description
lexa_parse_document	Parse document from URL with AI extraction
lexa_get_job_status	Check status of parsing job

Hippo Folder Tools

Tool	Description
hippo_create_folder	Create a new document folder
hippo_list_folders	List all folders
hippo_get_folder	Get folder details
hippo_delete_folder	Delete a folder and all contents

Hippo File Tools

Tool	Description
hippo_upload_file_url	Upload file from URL
hippo_list_files	List files in a folder
hippo_get_file	Get file details
hippo_delete_file	Delete a file

Hippo Chat/Q&A Tools

Tool	Description
hippo_create_chat	Create chat session for Q&A
hippo_list_chats	List all chat sessions
hippo_ask_question	Ask question with RAG (primary tool)
hippo_get_chat_history	Get conversation history
hippo_get_question_details	Get full details of a Q&A
hippo_delete_chat	Delete chat session

Account Tools

Tool	Description
account_get_info	Get account information
account_get_usage	Get usage metrics
account_get_plan	Get plan details and limits
account_list_users	List all users
account_get_current_user	Get current user info

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: [email protected]

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

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

Links

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

---

Made with ❤️ by the Cerevox team

Happy Building! 🔍 🦛 ✨