{
  "id": "mcp",
  "title": "RedisVL MCP",
  "url": "https://redis.io/docs/latest/develop/ai/redisvl/0.17.0/concepts/mcp/",
  "summary": "",
  "content": "\n\nRedisVL includes an MCP server that exposes a Redis-backed retrieval surface through a small, deterministic tool contract. It is designed for AI applications that want to search or maintain data in an existing Redis index without each client reimplementing Redis query logic.\n\n## What RedisVL MCP Does\n\nThe RedisVL MCP server sits between an MCP client and Redis:\n\n1. It connects to an existing Redis Search index.\n2. It inspects that index at startup and reconstructs its schema.\n3. It instantiates the configured vectorizer for query embedding and optional upsert embedding.\n4. It exposes stable MCP tools for search, and optionally upsert.\n\nThis keeps the Redis index as the source of truth for search behavior while giving MCP clients a predictable interface.\n\n## How RedisVL MCP Runs\n\nRedisVL MCP works with a focused model:\n\n- One server process binds to exactly one existing Redis index.\n- The server uses stdio transport.\n- Search behavior is owned by configuration, not by MCP callers.\n- The vectorizer is configured explicitly.\n- Upsert is optional and can be disabled with read-only mode.\n\n## Config-Owned Search Behavior\n\nMCP callers can control:\n\n- `query`\n- `limit`\n- `offset`\n- `filter`\n- `return_fields`\n\nThese request-time controls are still bounded by runtime config. In particular,\ndeep paging is limited by a configured maximum result window, enforced as\n`offset + limit`.\n\nMCP callers do not choose:\n\n- which index to target\n- whether retrieval is `vector`, `fulltext`, or `hybrid`\n- query tuning parameters such as hybrid fusion or vector runtime settings\n\nThat behavior lives in the server config under `indexes.\u003cid\u003e.search`. The response includes `search_type` as informational metadata, but it is not a request parameter.\n\n## Single Index Binding\n\nThe YAML config uses an `indexes` mapping with one configured entry. That binding points to an existing Redis index through `redis_name`, and every tool call targets that configured index.\n\n## Schema Inspection and Overrides\n\nRedisVL MCP is inspection-first:\n\n- the Redis index must already exist\n- the server reconstructs the schema from Redis metadata at startup\n- runtime field mappings remain explicit in config\n\nIn some environments, Redis metadata can be incomplete for vector field attributes. When that happens, `schema_overrides` can patch missing attrs for fields that were already discovered. It does not create new fields or change discovered field identity.\n\nStartup also validates that the inspected schema does not collide with\nMCP-reserved score metadata field names for the configured search mode.\n\n## Read-Only and Read-Write Modes\n\nRedisVL MCP always registers `search-records`.\n\n`upsert-records` is only registered when the server is not in read-only mode. Read-only mode is controlled by:\n\n- the CLI flag `--read-only`\n- or the environment variable `REDISVL_MCP_READ_ONLY=true`\n\nUse read-only mode when Redis is serving approved content to assistants and another system owns ingestion.\n\n## Tool Surface\n\nRedisVL MCP exposes two tools:\n\n- `search-records` searches the configured index using the server-owned search mode\n- `upsert-records` validates and upserts records, embedding them when needed\n\nThese tools follow a stable contract:\n\n- request validation happens before query or write execution\n- filters support either raw strings or a RedisVL-backed JSON DSL\n- error codes are mapped into a stable set of MCP-facing categories\n\n## Why Use MCP Instead of Direct RedisVL Calls\n\nUse RedisVL MCP when you want a standard tool boundary for agent frameworks or assistants that already speak MCP.\n\nUse direct RedisVL client code when your application should own index lifecycle, search construction, data loading, or richer RedisVL features directly in Python.\n\nRedisVL MCP is a good fit when:\n\n- multiple assistants should share one approved retrieval surface\n- you want search behavior fixed by deployment config\n- you need a read-only or tightly controlled write boundary\n- you want to reuse an existing Redis index without rebuilding retrieval logic in every client\n\nFor setup steps, config, commands, and examples, see [Run RedisVL MCP](../user_guide/how_to_guides/mcp.md).\n",
  "tags": [],
  "last_updated": "2026-04-21T14:39:33+02:00"
}