MCP Server - Mixpeek

The Mixpeek MCP (Model Context Protocol) server exposes all Mixpeek operations as tools that can be used by Claude, Claude Code, and other AI applications that support MCP.

What is MCP? The Model Context Protocol is an open protocol developed by Anthropic that standardizes how AI applications connect to external data sources and tools. Learn more about MCP

Overview

The Mixpeek MCP server provides 43 comprehensive tools covering all Mixpeek operations, allowing AI assistants to:

Create and manage namespaces, buckets, and collections
Upload and process files with feature extractors
Build multi-stage search pipelines
Execute semantic searches and retrievals
Manage taxonomies and clusters
Start conversational AI agent sessions

Features

Complete API Coverage

All 43 Mixpeek operations exposed as MCP tools

Dual Transport

Stdio for local development, HTTP/SSE for production

Native Integration

Shares database connections, no extra infrastructure

Streaming Support

Real-time responses for retrievers and agents

Quick Start

Connect to the Mixpeek MCP server using your existing API key. No infrastructure to manage!

Claude Desktop Setup

Add this to your Claude Desktop config: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mixpeek": {
      "url": "https://mcp.mixpeek.com",
      "headers": {
        "Authorization": "Bearer YOUR_MIXPEEK_API_KEY"
      }
    }
  }
}

Claude Code Setup

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "mixpeek": {
      "url": "https://mcp.mixpeek.com",
      "headers": {
        "Authorization": "Bearer YOUR_MIXPEEK_API_KEY"
      }
    }
  }
}

That’s it! Replace YOUR_MIXPEEK_API_KEY with your API key from the Mixpeek dashboard.

Need an API key? Sign up at mixpeek.com to get your free API key.

Available Tools

The MCP server exposes 43 tools across 9 categories:

Namespace Management (5 tools)

Manage isolated workspaces for multi-tenant applications.

Tool	Description
`create_namespace`	Create a new workspace
`list_namespaces`	List all namespaces
`get_namespace`	Get namespace details
`update_namespace`	Update namespace configuration
`delete_namespace`	Delete namespace

Bucket Management (6 tools)

File storage and object management.

Tool	Description
`create_bucket`	Create file storage bucket
`list_buckets`	List all buckets
`get_bucket`	Get bucket details
`update_bucket`	Update bucket configuration
`delete_bucket`	Delete bucket
`upload_object`	Upload file from URL or local path

Collection Management (7 tools)

Document collections with feature extraction.

Tool	Description
`create_collection`	Create collection with feature extractors
`list_collections`	List all collections
`get_collection`	Get collection details
`update_collection`	Update collection configuration
`clone_collection`	Clone existing collection
`trigger_collection`	Trigger processing pipeline
`delete_collection`	Delete collection

Document Management (5 tools)

CRUD operations on documents.

Tool	Description
`create_document`	Add document to collection
`list_documents`	Query documents with filters
`get_document`	Get document by ID
`update_document`	Update document data
`delete_document`	Delete document

Retriever Management (7 tools)

Multi-stage search pipelines with 23 retriever stages.

Tool	Description
`create_retriever`	Create multi-stage search pipeline
`list_retrievers`	List all retrievers
`get_retriever`	Get retriever configuration
`update_retriever`	Update retriever metadata
`clone_retriever`	Clone existing retriever
`execute_retriever`	Execute search pipeline
`delete_retriever`	Delete retriever

Supported Retriever Stages (23 total):

Search: feature_search, hybrid_search, semantic_search
Filter: attribute_filter, llm_filter, query_expand
Rank: sort_relevance, sort_attribute, rerank, mmr
Transform: group_by, aggregate, cluster, sample, summarize, json_transform
Enrich: document_enrich, taxonomy_enrich, llm_enrich
External: api_call, external_web_search, web_scrape, sql_lookup, code_execution, rag_prepare

Taxonomy Management (5 tools)

Hierarchical classification systems.

Tool	Description
`create_taxonomy`	Create classification hierarchy
`list_taxonomies`	List all taxonomies
`get_taxonomy`	Get taxonomy details
`execute_taxonomy`	Apply taxonomy classification
`delete_taxonomy`	Delete taxonomy

Cluster Management (4 tools)

Document clustering and discovery.

Tool	Description
`create_cluster`	Create clustering configuration
`list_clusters`	List all clusters
`execute_cluster`	Run clustering algorithm
`delete_cluster`	Delete cluster

Agent Management (3 tools)

Conversational AI sessions.

Tool	Description
`create_agent_session`	Start conversational AI session
`send_agent_message`	Send message to agent
`get_agent_history`	Get conversation history

Search (1 tool)

Global namespace search.

Tool	Description
`search_namespace`	Search across all resources

Usage Examples

Example 1: Create Collection with Feature Extractor

Ask Claude in natural language:

"Create a collection called 'videos' in my namespace with the multimodal
extractor to process video files with scene detection"

Claude will use the create_collection tool:

{
  "namespace_id": "ns_abc123",
  "collection_name": "videos",
  "feature_extractors": [
    {
      "feature_extractor_name": "multimodal_extractor",
      "version": "v1",
      "parameters": {
        "split_method": "scene",
        "scene_detection_threshold": 0.3,
        "run_transcription": true,
        "run_video_description": true
      }
    }
  ]
}

Example 2: Build Multi-Stage Retriever

Ask Claude:

"Create a retriever that searches my videos collection, reranks the top 50
results with Cohere to get the best 10, and adds GPT-4 summaries"

Claude uses create_retriever:

{
  "namespace_id": "ns_abc123",
  "retriever_name": "video-search",
  "collection_identifiers": ["videos"],
  "stages": [
    {
      "stage_name": "feature_search",
      "parameters": {
        "features": ["multimodal"],
        "top_k": 50,
        "min_score": 0.7
      }
    },
    {
      "stage_name": "rerank",
      "parameters": {
        "inference_name": "cohere-rerank",
        "top_k": 10
      }
    },
    {
      "stage_name": "llm_enrich",
      "parameters": {
        "inference_name": "gpt-4",
        "fields_to_generate": [
          {
            "name": "summary",
            "prompt": "Summarize this video segment in 2 sentences"
          }
        ]
      }
    }
  ]
}

Example 3: Execute Search

Ask Claude:

"Search for videos about machine learning tutorials using the video-search retriever"

Claude uses execute_retriever:

{
  "namespace_id": "ns_abc123",
  "retriever_id": "ret_xyz789",
  "inputs": {
    "query": "machine learning tutorial"
  }
}

Authentication

The MCP server uses your existing Mixpeek API key for authentication. Each tool call is authenticated using the same permission system as the REST API. Security Features:

✅ All requests authenticated via API key
✅ Same RBAC permissions as REST API
✅ Automatic rate limiting per organization
✅ Audit logging for all operations
✅ TLS encryption for all connections

Keep your API key secure! Never commit API keys to version control or share them publicly.

How It Works

The Mixpeek MCP server is a hosted service that provides a Model Context Protocol interface to all Mixpeek operations. Architecture:

┌─────────────────┐
│  Claude Desktop │
│  or Claude Code │
└────────┬────────┘
         │ HTTP/SSE + API Key
         │
         ▼
┌─────────────────────────┐
│   MCP Server (Hosted)   │
│  https://mcp.mixpeek.com │
├─────────────────────────┤
│  • 43 MCP Tools         │
│  • API Key Auth         │
│  • SSE Streaming        │
│  • Rate Limiting        │
└────────┬────────────────┘
         │ Direct Service Calls
         │
         ▼
┌─────────────────────────┐
│   Mixpeek Services      │
├─────────────────────────┤
│  • MongoDB (metadata)   │
│  • Redis (cache)        │
│  • Qdrant (vectors)     │
│  • S3 (storage)         │
└─────────────────────────┘

Key Features:

Fully Managed: No infrastructure to deploy or maintain
Shared Resources: Uses the same databases as the REST API
Real-time Streaming: SSE support for retriever and agent responses
Secure: TLS encryption, API key authentication, rate limiting

Testing

The MCP server includes comprehensive tests:

# Run all tests
pytest mixpeek_mcp/tests/ -v

# Run specific test modules
pytest mixpeek_mcp/tests/test_auth.py -v
pytest mixpeek_mcp/tests/test_tools.py -v
pytest mixpeek_mcp/tests/test_server.py -v

# Run with coverage
pytest mixpeek_mcp/tests/ --cov=mixpeek_mcp --cov-report=html

Use Cases

AI-Powered Content Search

Use Claude to build and execute complex search pipelines across your multimodal content:

“Find all video segments mentioning product demos in Q4”
“Show me documents about pricing that were uploaded last month”
“Search for images with people smiling in outdoor settings”

Automated Pipeline Creation

Let Claude configure your entire data processing pipeline:

“Set up a collection to process PDFs with OCR and extract tables”
“Create a retriever that searches videos by transcript and visual similarity”
“Build a taxonomy to classify customer support tickets”

Data Exploration & Analysis

Explore your data conversationally:

“What collections do I have and how many documents are in each?”
“Show me the most recent uploads to my images bucket”
“Find clusters of similar documents in my research collection”

RAG Application Development

Build RAG applications using natural language:

“Create a retriever that searches my knowledge base and prepares results for GPT-4”
“Add a reranking stage to improve relevance”
“Enrich results with summaries and key points”

Troubleshooting

MCP Server Not Connecting

Issue: Claude Code can’t connect to the MCP server Solutions:

Verify the cwd path is correct in your MCP configuration
Check that all environment variables are set (MONGO_URI, REDIS_URL, etc.)
Run the server manually to see error messages: python -m mixpeek_mcp.main --transport stdio
Check Claude Code logs for connection errors

Tool Execution Fails

Issue: Tools return errors when executed Solutions:

Verify your Mixpeek API key is valid
Ensure the namespace exists before creating resources in it
Check that required services (MongoDB, Redis, Qdrant) are running
Review tool parameters match the expected schema

Slow Response Times

Issue: MCP tools are slow to respond Solutions:

For local development, use stdio transport (faster than HTTP)
Increase timeout settings if processing large files
Check database connection pool settings
Monitor Redis and Qdrant performance

Next Steps

Core Concepts

Learn about Mixpeek’s data model

Feature Extractors

Explore available feature extractors

Retriever Stages

Learn about retriever stages

API Reference

View complete API documentation

Additional Resources

Questions or issues? File an issue on GitHub or contact Mixpeek support.

Integrations

​Overview

​Features

Complete API Coverage

Dual Transport

Native Integration

Streaming Support

​Quick Start

​Claude Desktop Setup

​Claude Code Setup

​Available Tools

​Namespace Management (5 tools)

​Bucket Management (6 tools)

​Collection Management (7 tools)

​Document Management (5 tools)

​Retriever Management (7 tools)

​Taxonomy Management (5 tools)

​Cluster Management (4 tools)

​Agent Management (3 tools)

​Search (1 tool)

​Usage Examples

​Example 1: Create Collection with Feature Extractor

​Example 2: Build Multi-Stage Retriever

​Example 3: Execute Search

​Authentication

​How It Works

​Testing

​Use Cases

​Troubleshooting

​MCP Server Not Connecting

​Tool Execution Fails

​Slow Response Times

​Next Steps

Core Concepts

Feature Extractors

Retriever Stages

API Reference

​Additional Resources

Overview

Features

Quick Start

Claude Desktop Setup

Claude Code Setup

Available Tools

Namespace Management (5 tools)

Bucket Management (6 tools)

Collection Management (7 tools)

Document Management (5 tools)

Retriever Management (7 tools)

Taxonomy Management (5 tools)

Cluster Management (4 tools)

Agent Management (3 tools)

Search (1 tool)

Usage Examples

Example 1: Create Collection with Feature Extractor

Example 2: Build Multi-Stage Retriever

Example 3: Execute Search

Authentication

How It Works

Testing

Use Cases

Troubleshooting

MCP Server Not Connecting

Tool Execution Fails

Slow Response Times

Next Steps

Additional Resources