> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Give AI agents access to video, image, and audio search through the Model Context Protocol Connect Claude (or any MCP-compatible client) to Mixpeek so it can search video, image, and audio content. ## 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](#sign-in-with-oauth). > [!TIP] > > For a focused search agent, use the [Per-Retriever Server](#per-retriever-mcp-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](https://studio.mixpeek.com). To connect without a key, use the [App server over OAuth](#sign-in-with-oauth). > [tab] Claude Desktop > > Add this to your Claude Desktop config file (`claude_desktop_config.json`): > > ```json Full theme={null} > { > "mcpServers": { > "mixpeek": { > "url": "https://mcp.mixpeek.com/mcp", > "headers": { > "Authorization": "Bearer YOUR_API_KEY" > } > } > } > } > ``` > > ```json Ingestion theme={null} > { > "mcpServers": { > "mixpeek-ingestion": { > "url": "https://mcp.mixpeek.com/ingestion/mcp", > "headers": { > "Authorization": "Bearer YOUR_API_KEY" > } > } > } > } > ``` > > ```json Retrieval theme={null} > { > "mcpServers": { > "mixpeek-retrieval": { > "url": "https://mcp.mixpeek.com/retrieval/mcp", > "headers": { > "Authorization": "Bearer YOUR_API_KEY" > } > } > } > } > ``` > > ```json Admin theme={null} > { > "mcpServers": { > "mixpeek-admin": { > "url": "https://mcp.mixpeek.com/admin/mcp", > "headers": { > "Authorization": "Bearer YOUR_API_KEY" > } > } > } > } > ``` > [tab] Claude Code > > 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`. > > ```bash Full theme={null} > claude mcp add --scope user --transport http mixpeek https://mcp.mixpeek.com/mcp \ > --header "Authorization: Bearer YOUR_API_KEY" > ``` > > ```bash Ingestion theme={null} > claude mcp add --scope user --transport http mixpeek-ingestion https://mcp.mixpeek.com/ingestion/mcp \ > --header "Authorization: Bearer YOUR_API_KEY" > ``` > > ```bash Retrieval theme={null} > claude mcp add --scope user --transport http mixpeek-retrieval https://mcp.mixpeek.com/retrieval/mcp \ > --header "Authorization: Bearer YOUR_API_KEY" > ``` > > ```bash Admin theme={null} > claude mcp add --scope user --transport http mixpeek-admin https://mcp.mixpeek.com/admin/mcp \ > --header "Authorization: Bearer YOUR_API_KEY" > ``` > [tab] Cursor > > Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in your project: > > ```json App (OAuth) theme={null} > { > "mcpServers": { > "mixpeek": { > "url": "https://mcp.mixpeek.com/app/mcp" > } > } > } > ``` > > ```json Full (API key) theme={null} > { > "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](#hosted-server-urls). ### Sign in with OAuth 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. 1. Add the URL to your client with no `Authorization` header. 2. 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`. 3. Your client opens the Mixpeek sign-in page at `auth.mixpeek.com` and requests the `mixpeek:read` scope. 4. 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. **1. Install** ```bash theme={null} pip install mixpeek-mcp-retriever ``` **2. Run** ```bash theme={null} mixpeek-mcp-retriever \ --retriever-id ret_xxx \ --namespace-id ns_xxx \ --api-key YOUR_API_KEY ``` **3. Connect** Add to your Claude Desktop config: ```json theme={null} { "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. | > [!NOTE] > > 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: ```bash theme={null} 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_`): ```bash theme={null} 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 98 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 -- 50 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_evaluation_dataset` | Create an evaluation dataset: queries with their relevant documents (or values of `relevance_field`) | | `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 | | `discover` | Read the catalog a manifest is built from: extractors, models, retriever stages and the manifest schema with an example | | `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 | | `generate_manifest` | Generate a namespace manifest from a description of the use case. Send `inventory` (files per bucket) and `queries_per_month` to get its quote in the same answer | | `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_evaluation` | Read an evaluation's status and its overall and per-query metrics | | `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_namespace_templates` | List the namespace templates: ready manifests for one use case each, with their models and price | | `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 | | `quote_manifest` | Quote a namespace before anything runs: send `manifest`, `inventory` (files per bucket) and `queries_per_month`; returns what indexing is charged, the monthly price and the unit prices, per collection | | `restore_snapshot` | Restore a namespace from one of its snapshots | | `run_evaluation` | Grade a retriever on a dataset: precision, recall, F1, F2, NDCG at fixed k and at multiples of each query's relevant count | | `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](#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. > [!WARNING] > > 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 > [accordion] 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 > [accordion] Tools return 'Unauthorized' or 'Invalid API key' > > * Verify your API key at [studio.mixpeek.com](https://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 > [accordion] 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 > [accordion] 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 > [accordion] 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 > [card] [LangChain Integration](https://docs.mixpeek.com/docs/agent-integrations/langchain.md) > > Use Mixpeek as a LangChain tool > [card] [Retriever Stages](https://docs.mixpeek.com/docs/retrieval/stages/overview.md) > > Configure multi-stage search pipelines > [card] [Feature Extractors](https://docs.mixpeek.com/docs/processing/feature-extractors.md) > > Choose the right extractor for your data > [card] [Core Concepts](https://docs.mixpeek.com/docs/overview/concepts.md) > > Understand namespaces, collections, and documents This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.