MCP Server

Connect Claude (or any MCP-compatible client) to Mixpeek so it can search video, image, and audio content.

Mixpeek MCP server architecture: an MCP client connects over HTTPS with a Bearer API key to the scope-gated Mixpeek MCP server (91 tools), which exposes retrievers as tools — agent_search for autonomous multimodal retrieval, retriever_execute for multi-stage filter/join/rerank pipelines, features_get for faces, scenes, OCR, transcripts and embeddings, and agentic_enrich (ingestion scope, off by default) — operating on a Mixpeek namespace of video, images, audio and documents stored as features plus dense, sparse and BM25 vectors on object storage. — An MCP client (Claude, Cursor, VS Code, or your agent) authenticates with a Bearer API key and gets scope-gated tools — agent_search, retriever_execute, features_get, and (ingestion scope, off by default) agentic_enrich — that search and enrich the multimodal features and vectors in your Mixpeek namespace.

Hosted Server URLs

Mixpeek runs five hosted MCP servers. Each exposes a different subset of tools, so you load only what your agent needs.

Scope	URL	Auth	Tools
Full	`https://mcp.mixpeek.com/mcp`	API key	66: everything
Ingestion	`https://mcp.mixpeek.com/ingestion/mcp`	API key	27: buckets, collections, documents, storage connections
Retrieval	`https://mcp.mixpeek.com/retrieval/mcp`	API key	18: retrievers, agents, marketplace, search
Admin	`https://mcp.mixpeek.com/admin/mcp`	API key	23: namespaces, taxonomies, clusters, storage connections
App	`https://mcp.mixpeek.com/app/mcp`	OAuth (`mixpeek:read`)	9: read-only browse and search

The App server is read-only. You sign in with your Mixpeek account in the browser, so you never paste a key into the client. See Sign in with OAuth.

For a focused search agent, use the Per-Retriever Server instead. It exposes a single typed search tool generated from your retriever’s input schema.

Setup

Replace YOUR_API_KEY with your key from the Mixpeek Studio. To connect without a key, use the App server over OAuth.

Claude Desktop
Claude Code
Cursor

Add this to your Claude Desktop config file (claude_desktop_config.json):

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

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

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

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

Run this in your terminal. To set up Claude Code, Codex, Gemini CLI and Cursor in one step instead, run curl -fsSL https://mixpeek.com/install | sh.

claude mcp add --scope user --transport http mixpeek https://mcp.mixpeek.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

claude mcp add --scope user --transport http mixpeek-ingestion https://mcp.mixpeek.com/ingestion/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

claude mcp add --scope user --transport http mixpeek-retrieval https://mcp.mixpeek.com/retrieval/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

claude mcp add --scope user --transport http mixpeek-admin https://mcp.mixpeek.com/admin/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "mixpeek": {
      "url": "https://mcp.mixpeek.com/app/mcp"
    }
  }
}

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

With the App config, Cursor opens a Mixpeek sign-in page the first time it connects. To use a scoped key-based server instead, swap the URL for one from the table above.

The App server at https://mcp.mixpeek.com/app/mcp uses OAuth 2.1. It exposes 9 read-only tools: list and read namespaces, collections, documents and retrievers, run a retriever, and search a namespace.

Add the URL to your client with no Authorization header.
On first connect, the server answers 401 with a WWW-Authenticate header that names its metadata at https://mcp.mixpeek.com/.well-known/oauth-protected-resource/app/mcp.
Your client opens the Mixpeek sign-in page at auth.mixpeek.com and requests the mixpeek:read scope.
After you approve, the client stores the token and the tools load.

The sign-in acts as you in your Mixpeek organization, with your role’s permissions. The App server exposes read tools only, so an OAuth connection can search and read but not change anything. For testing, the App server also accepts a Mixpeek API key in Authorization: Bearer YOUR_API_KEY.

Per-Retriever MCP Server

The retriever server is a lightweight MCP server scoped to a single retriever. It reads your retriever’s input_schema at startup and generates a typed search tool whose parameters match exactly.

Install

pip install mixpeek-mcp-retriever

Run

mixpeek-mcp-retriever \
  --retriever-id ret_xxx \
  --namespace-id ns_xxx \
  --api-key YOUR_API_KEY

Connect

Add to your Claude Desktop config:

{
  "mcpServers": {
    "my-search": {
      "command": "mixpeek-mcp-retriever",
      "args": [
        "--retriever-id", "ret_xxx",
        "--namespace-id", "ns_xxx",
        "--api-key", "YOUR_API_KEY"
      ]
    }
  }
}

The retriever server exposes three tools:

Tool	Description
`search`	Execute the retriever. Parameters are generated from the retriever’s `input_schema` — field names, types, required flags, enums, and descriptions. Pagination (`page`, `page_size`) is added automatically.
`describe`	Returns structured metadata: retriever ID, name, collections, input fields, and stage configuration.
`explain`	Returns a human-readable explanation of the pipeline: what each stage does, in order.

If your retriever’s input_schema has a field named page or page_size, the pagination parameters are automatically renamed to _pagination_page and _pagination_page_size to avoid conflicts.

You can also run the retriever server over HTTP for deployed agents:

mixpeek-mcp-retriever \
  --retriever-id ret_xxx \
  --namespace-id ns_xxx \
  --api-key YOUR_API_KEY \
  --transport http \
  --port 8081

Or configure everything via environment variables (prefixed with RETRIEVER_MCP_):

export RETRIEVER_MCP_RETRIEVER_ID=ret_xxx
export RETRIEVER_MCP_NAMESPACE_ID=ns_xxx
export RETRIEVER_MCP_API_KEY=YOUR_API_KEY
export RETRIEVER_MCP_TRANSPORT=stdio
mixpeek-mcp-retriever

Available Tools by Scope

The full scope serves all 91 tools. The App scope is a read-only subset of them. The three key-based scopes below overlap: list_storage_connections and get_storage_connection are in two of them, which is why the per-scope counts sum to more than the total.

Ingestion — 29 tools

Tool	Description
`clone_collection`	Clone an existing collection with optional overrides
`create_bucket`	Create a new bucket for file storage and processing
`create_bucket_sync`	Attach a storage connection to a bucket so its objects are ingested
`create_collection`	Create a new collection for processing and searching documents
`create_document`	Create a new document in a collection
`delete_bucket`	Delete a bucket and all its objects
`delete_collection`	Delete a collection and all its documents
`delete_document`	Delete a document from a collection
`get_bucket`	Get details of a specific bucket
`get_bucket_sync`	Get one sync configuration, including its status and counters
`get_collection`	Get details of a specific collection
`get_collection_failures`	Why documents in one collection failed to process, grouped by cause
`get_collection_lifecycle`	Get the storage lifecycle status of a collection, including current tier (active/cold/archived), vector counts, and last transition timestamp
`get_collection_overview`	Document counts and processing state for one collection
`get_document`	Get a specific document by ID
`get_storage_connection`	Get one storage connection by id or name
`list_bucket_syncs`	List the sync configurations on a bucket
`list_buckets`	List all buckets in a namespace
`list_collections`	List all collections in a namespace
`list_documents`	List documents in a collection with filters
`list_storage_connections`	List storage connections in the organization
`transition_collection_lifecycle`	Transition a collection’s storage tier
`trigger_bucket_sync`	Run a sync configuration now instead of waiting for its schedule
`trigger_collection`	Trigger collection processing on bucket objects
`update_bucket`	Update bucket configuration
`update_collection`	Update collection configuration
`update_document`	Update a document’s data
`upload_object`	Upload an object (file) to a bucket
`upsert_documents_byo`	Upsert documents with pre-computed vectors directly into a namespace

Retrieval — 21 tools

Tool	Description
`agent_signup`	Get a Mixpeek API key and namespace without a browser, for an agent acting for a named person
`clone_retriever`	Clone an existing retriever with optional modifications
`create_agent_session`	Create a new conversational agent session
`create_interaction`	Record a user interaction (click, view, conversion) against a retriever result
`create_retriever`	Create a multi-stage search pipeline
`delete_retriever`	Delete a retriever
`execute_marketplace_retriever`	Run a public marketplace retriever by name against its hosted dataset
`execute_retriever`	Execute a retriever pipeline with inputs and get search results
`get_agent_history`	Get conversation history for an agent session
`get_marketplace_listing`	Get one marketplace listing, including the inputs its execute call expects
`get_marketplace_template`	Get a marketplace listing’s stages, to create the same retriever over your own collections
`get_retriever`	Get details of a specific retriever including all stages
`get_retriever_performance`	Latency and volume for one retriever over a time range
`get_retriever_slow_queries`	The slowest recent queries on one retriever
`list_interactions`	List recorded interactions, for inspecting or auditing the learning signal
`list_marketplace`	List the public retrievers Mixpeek hosts over sample datasets
`list_retrievers`	List all retrievers in a namespace
`respond_to_agent_confirmation`	Approve or reject the write an agent session paused on, and get the rest of its response
`search_namespace`	Search across all resources in a namespace (buckets, collections, retrievers, etc.)
`send_agent_message`	Send a message to an agent session and get a response; a write pauses for `respond_to_agent_confirmation`
`update_retriever`	Update retriever configuration

Admin — 43 tools

Tool	Description
`apply_manifest`	Apply a manifest: create or update the resources it declares
`create_alert`	Create an alert that runs a retriever against new documents and notifies a webhook, email or Slack channel when it matches
`create_cluster`	Create a document clustering configuration
`create_namespace`	Create a new namespace (workspace) for organizing collections and resources
`create_snapshot`	Take a point-in-time snapshot of a namespace
`create_standalone_namespace`	Create a standalone namespace for BYO vectors
`create_storage_connection`	Create a storage connection to an external source (S3, Google Drive, RTSP camera, and others)
`create_taxonomy`	Create a hierarchical classification taxonomy
`create_webhook`	Create a webhook that posts events (batch finished, documents updated and others) to a URL
`delete_alert`	Delete an alert
`delete_cluster`	Delete a cluster configuration
`delete_namespace`	Delete a namespace and all its resources
`delete_storage_connection`	Delete a storage connection
`delete_taxonomy`	Delete a taxonomy
`delete_webhook`	Delete a webhook
`diff_manifest`	Show what applying a manifest would create, change or leave alone
`execute_cluster`	Execute clustering algorithm on a collection
`execute_taxonomy`	Apply taxonomy classification to document data
`export_manifest`	Export a namespace’s resources as a manifest
`get_alert`	Get one alert by ID or name
`get_billing_transactions`	List individual credit transactions (the per-operation ledger): each debit, what consumed it, the namespace it’s attributed to, and when
`get_credit_balance`	Get the organization’s current credit balance, account tier, daily burn rate, and estimated days remaining
`get_namespace`	Get details of a specific namespace by ID or name
`get_namespace_errors`	Recent errors across a namespace
`get_snapshot`	Get one snapshot, including its status and size
`get_storage_connection`	Get one storage connection by id or name
`get_taxonomy`	Get details of a specific taxonomy
`get_usage_breakdown`	Get itemized credit usage for a billing month — broken down by operation, by extractor, by namespace (per-client/team chargeback), and by retriever (per-product cost)
`get_usage_summary`	Credit usage summary for the organization
`get_webhook`	Get one webhook
`list_alerts`	List the namespace’s alerts
`list_clusters`	List all cluster configurations in a namespace
`list_namespaces`	List all namespaces in the organization
`list_snapshots`	List a namespace’s snapshots
`list_storage_connections`	List storage connections in the organization
`list_taxonomies`	List all taxonomies in a namespace
`list_webhooks`	List the organization’s webhooks
`restore_snapshot`	Restore a namespace from one of its snapshots
`test_storage_connection`	Test a storage connection against the live source and report what it found
`update_namespace`	Update namespace configuration
`update_webhook`	Update a webhook’s URL, events or enabled state
`validate_manifest`	Validate a Mixpeek manifest (namespaces, buckets, collections, retrievers) without applying it
`verify_snapshot`	Check that a snapshot is complete and restorable

App — 9 tools

Served at https://mcp.mixpeek.com/app/mcp behind OAuth. Every tool is read-only.

Tool	Description
`execute_retriever`	Execute a retriever pipeline with inputs and get search results
`get_collection`	Get details of a specific collection
`get_document`	Get a specific document by ID
`get_retriever`	Get details of a specific retriever including all stages
`list_collections`	List all collections in a namespace
`list_documents`	List documents in a collection with filters
`list_namespaces`	List all namespaces in the organization
`list_retrievers`	List all retrievers in a namespace
`search_namespace`	Search across all resources in a namespace (buckets, collections, retrievers, etc.)

Authentication

The Full, Ingestion, Retrieval and Admin servers authenticate with your Mixpeek API key. The key carries the same RBAC permissions as the REST API. The App server uses OAuth instead.

App server: Your client signs you in through OAuth 2.1 with the mixpeek:read scope. See Sign in with OAuth.
Hosted servers (HTTP): Pass the key in the Authorization: Bearer YOUR_API_KEY header. The server injects it into every tool call.
Stdio servers: Set the MIXPEEK_API_KEY environment variable, or pass --api-key as a CLI argument.

Never commit API keys to version control. For deployed agents, use environment variables or a secrets manager.

Example Conversation

Here is what a session looks like with the Retrieval server connected:

You: "Find all video clips where someone mentions quarterly revenue"
Claude: [calls execute_retriever with query="quarterly revenue"]
--> Returns 8 matching video segments with timestamps and transcript excerpts.

You: "Summarize the top 3 results"
Claude: [calls execute_retriever with query="quarterly revenue", then processes results]
--> "1. Q3 earnings call (2:34) -- CFO reports 22% YoY growth.
     2. Board presentation (14:12) -- Revenue breakdown by region.
     3. Team standup (0:45) -- Quick mention of hitting quarterly target."

You: "Create a retriever that searches product images by description and filters by brand"
Claude: [calls create_retriever with feature_search + attribute_filter stages]
--> "Created retriever ret_abc123 with 2 stages: feature search on image
     embeddings, then attribute filter on the brand field."

And with the per-retriever server:

You: "What does this retriever do?"
Claude: [calls describe]
--> "This is 'Product Search' -- searches your products collection
     by text query with an optional category filter, using
     feature search -> attribute filter -> reranking."

You: "Search for wireless headphones under electronics"
Claude: [calls search with query="wireless headphones", category="electronics"]
--> Returns top 10 matching products with scores and metadata.

You: "Explain the pipeline"
Claude: [calls explain]
--> "1. feature_search: embeds your query and finds the top 50 matches.
     2. attribute_filter: filters by category.
     3. rerank: reranks with Cohere down to the top 10."

Architecture

+-----------------------------------------------------------+
|                   Claude / AI Agent                       |
+-----------------------------+-----------------------------+
                              | MCP Protocol (HTTP / Stdio)
                              v
+-----------------------------------------------------------+
|              Mixpeek MCP Server                           |
|  +--------+ +-----------+ +-----------+ +--------+       |
|  |  Full  | | Ingestion | | Retrieval | | Admin  |       |
|  | (66)   | |   (27)    | |   (18)    | |  (23)  |       |
|  +---+----+ +-----+-----+ +-----+-----+ +---+----+       |
|      +------------+-------------+-----------+             |
|                    Tool Handlers                          |
+-----------------------------+-----------------------------+
                              |       +--------------------+
                              |       | Retriever Server   |
                              |       | (per-retriever, 3) |
                              |       +---------+----------+
                              +--------+--------+
                                       | API calls
                                       v
                            +----------------------+
                            |   Mixpeek Platform   |
                            +----------------------+

The scoped servers share the same codebase. Scoping controls which tools are registered, not how they execute. Each scope is mounted at its own path prefix (/ingestion, /retrieval, /admin) while the full server runs at /mcp. The App server runs at /app/mcp.

Troubleshooting

Claude can't connect to the MCP server

Verify the URL is correct (e.g. https://mcp.mixpeek.com/ingestion/mcp)
Check that the Authorization header format is Bearer YOUR_API_KEY
Restart Claude Desktop or Claude Code after changing config

Tools return 'Unauthorized' or 'Invalid API key'

Verify your API key at studio.mixpeek.com
Check that the key has permissions for the namespace you’re accessing
Make sure there are no extra spaces in the key

Tool not found (404)

You may be calling a tool on the wrong scoped server (e.g. execute_retriever on /ingestion)
Use the full server if you need all tools

Retriever Server fails to start

Ensure --retriever-id and --namespace-id are correct
Verify the API key has access to that namespace
Check that the retriever exists via the API

Search returns empty results

Confirm your collection has processed documents (not just uploaded files)
Check that the retriever’s feature_uri matches your collection’s extractor
Try a broader query or remove optional filters

Next Steps

LangChain Integration

Use Mixpeek as a LangChain tool

Retriever Stages

Configure multi-stage search pipelines

Feature Extractors

Choose the right extractor for your data

Core Concepts

Understand namespaces, collections, and documents

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

Hosted Server URLs

Setup

Per-Retriever MCP Server

Available Tools by Scope

Ingestion — 29 tools

Retrieval — 21 tools

Admin — 43 tools

App — 9 tools

Authentication

Example Conversation

Architecture

Troubleshooting

Next Steps

LangChain Integration

Retriever Stages

Feature Extractors

Core Concepts

​Hosted Server URLs

​Setup

​Sign in with OAuth

​Per-Retriever MCP Server

​Available Tools by Scope

​Ingestion — 29 tools

​Retrieval — 21 tools

​Admin — 43 tools

​App — 9 tools

​Authentication

​Example Conversation

​Architecture

​Troubleshooting

​Next Steps

LangChain Integration

Retriever Stages

Feature Extractors

Core Concepts

Hosted Server URLs

Setup

Sign in with OAuth

Per-Retriever MCP Server

Available Tools by Scope

Ingestion — 29 tools

Retrieval — 21 tools

Admin — 43 tools

App — 9 tools

Authentication

Example Conversation

Architecture

Troubleshooting

Next Steps