feat: add RedisVL MCP server and documentation

.gitignore

@@ -189,6 +189,9 @@ dmypy.json
 # Cython debug symbols
 cython_debug/
 
+# Codex
+.codex/
+
 # PyCharm
 #  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore

README.md

@@ -35,6 +35,7 @@ Perfect for building **RAG pipelines** with real-time retrieval, **AI agents** w
 | **[Vector Search](#retrieval)**<br/>*Similarity search with metadata filters* | **[LLM Memory](#llm-memory)**<br/>*Agentic AI context management* | **Async Support**<br/>*Async indexing and search for improved performance* |
 | **[Complex Filtering](#retrieval)**<br/>*Combine multiple filter types* | **[Semantic Routing](#semantic-routing)**<br/>*Intelligent query classification* | **[Vectorizers](#vectorizers)**<br/>*8+ embedding provider integrations* |
 | **[Hybrid Search](#retrieval)**<br/>*Combine semantic & full-text signals* | **[Embedding Caching](#embedding-caching)**<br/>*Cache embeddings for efficiency* | **[Rerankers](#rerankers)**<br/>*Improve search result relevancy* |
+|  |  | **[MCP Server](#mcp-server)**<br/>*Expose an existing Redis index to MCP clients* |
 
 </div>
 
@@ -50,7 +51,16 @@ Install `redisvl` into your Python (>=3.9) environment using `pip`:
 pip install redisvl
 ```
 
+Install the MCP server extra when you want to expose an existing Redis index through MCP:
+
+```bash
+pip install redisvl[mcp]
+```
+
+The `redisvl[mcp]` extra requires Python 3.10 or newer.
+
 > For more detailed instructions, visit the [installation guide](https://docs.redisvl.com/en/latest/user_guide/installation.html).
+> For MCP concepts and setup, see the [RedisVL MCP docs](https://docs.redisvl.com/en/latest/concepts/mcp.html) and the [MCP how-to guide](https://docs.redisvl.com/en/latest/user_guide/how_to_guides/mcp.html).
 
 ## Redis
 
@@ -525,11 +535,45 @@ usage: rvl <command> [<args>]
 
 Commands:
         index       Index manipulation (create, delete, etc.)
+        mcp         Run the RedisVL MCP server
         version     Obtain the version of RedisVL
         stats       Obtain statistics about an index
 ```
 
-> Read more about [using the CLI](https://docs.redisvl.com/en/latest/overview/cli.html).
+Run the MCP server over stdio with:
+
+```bash
+uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml
+```
+
+Use `--read-only` to expose search without upsert.
+
+> Read more about [using the CLI](https://docs.redisvl.com/en/latest/overview/cli.html) and [running RedisVL MCP](https://docs.redisvl.com/en/latest/user_guide/how_to_guides/mcp.html).
+
+### MCP Server
+
+RedisVL includes an MCP server that lets MCP-compatible clients search or upsert data in an existing Redis index through a small, stable tool contract.
+
+The server:
+
+- connects to one existing Redis Search index
+- reconstructs the schema from Redis at startup
+- uses the configured vectorizer for query embedding and optional upsert embedding
+- exposes `search-records` and, unless read-only mode is enabled, `upsert-records`
+
+Run it over stdio with:
+
+```bash
+uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml
+```
+
+Use `--read-only` when clients should only search:
+
+```bash
+uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml --read-only
+```
+
+For configuration details, tool arguments, and examples, see the [RedisVL MCP docs](https://docs.redisvl.com/en/latest/concepts/mcp.html) and the [MCP how-to guide](https://docs.redisvl.com/en/latest/user_guide/how_to_guides/mcp.html).
 
 ## 🚀 Why RedisVL?
 
@@ -542,6 +586,7 @@ Built on the [Redis Python](https://github.com/redis/redis-py/tree/master) clien
 For additional help, check out the following resources:
 
 - [Getting Started Guide](https://docs.redisvl.com/en/stable/user_guide/01_getting_started.html)
+- [RedisVL MCP](https://docs.redisvl.com/en/latest/concepts/mcp.html)
 - [API Reference](https://docs.redisvl.com/en/stable/api/index.html)
 - [Redis AI Recipes](https://github.com/redis-developer/redis-ai-resources)
 

docs/concepts/index.md

@@ -47,6 +47,13 @@ Vector, filter, text, hybrid, and multi-vector query options.
 Vectorizers for embeddings and rerankers for result optimization.
 :::
 
+:::{grid-item-card} 🧠 MCP
+:link: mcp
+:link-type: doc
+
+How RedisVL exposes an existing Redis index to MCP clients through a stable tool contract.
+:::
+
 :::{grid-item-card} 🧩 Extensions
 :link: extensions
 :link-type: doc
@@ -65,5 +72,6 @@ search-and-indexing
 field-attributes
 queries
 utilities
+mcp
 extensions
 ```

docs/concepts/mcp.md

@@ -0,0 +1,102 @@
+---
+myst:
+  html_meta:
+    "description lang=en": |
+      RedisVL MCP concepts: how the RedisVL MCP server exposes an existing Redis index to MCP clients.
+---
+
+# RedisVL MCP
+
+RedisVL 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.
+
+## What RedisVL MCP Does
+
+The RedisVL MCP server sits between an MCP client and Redis:
+
+1. It connects to an existing Redis Search index.
+2. It inspects that index at startup and reconstructs its schema.
+3. It instantiates the configured vectorizer for query embedding and optional upsert embedding.
+4. It exposes stable MCP tools for search, and optionally upsert.
+
+This keeps the Redis index as the source of truth for search behavior while giving MCP clients a predictable interface.
+
+## How RedisVL MCP Runs
+
+RedisVL MCP works with a focused model:
+
+- One server process binds to exactly one existing Redis index.
+- The server uses stdio transport.
+- Search behavior is owned by configuration, not by MCP callers.
+- The vectorizer is configured explicitly.
+- Upsert is optional and can be disabled with read-only mode.
+
+## Config-Owned Search Behavior
+
+MCP callers can control:
+
+- `query`
+- `limit`
+- `offset`
+- `filter`
+- `return_fields`
+
+MCP callers do not choose:
+
+- which index to target
+- whether retrieval is `vector`, `fulltext`, or `hybrid`
+- query tuning parameters such as hybrid fusion or vector runtime settings
+
+That behavior lives in the server config under `indexes.<id>.search`. The response includes `search_type` as informational metadata, but it is not a request parameter.
+
+## Single Index Binding
+
+The 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.
+
+## Schema Inspection and Overrides
+
+RedisVL MCP is inspection-first:
+
+- the Redis index must already exist
+- the server reconstructs the schema from Redis metadata at startup
+- runtime field mappings remain explicit in config
+
+In 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.
+
+## Read-Only and Read-Write Modes
+
+RedisVL MCP always registers `search-records`.
+
+`upsert-records` is only registered when the server is not in read-only mode. Read-only mode is controlled by:
+
+- the CLI flag `--read-only`
+- or the environment variable `REDISVL_MCP_READ_ONLY=true`
+
+Use read-only mode when Redis is serving approved content to assistants and another system owns ingestion.
+
+## Tool Surface
+
+RedisVL MCP exposes two tools:
+
+- `search-records` searches the configured index using the server-owned search mode
+- `upsert-records` validates and upserts records, embedding them when needed
+
+These tools follow a stable contract:
+
+- request validation happens before query or write execution
+- filters support either raw strings or a RedisVL-backed JSON DSL
+- error codes are mapped into a stable set of MCP-facing categories
+
+## Why Use MCP Instead of Direct RedisVL Calls
+
+Use RedisVL MCP when you want a standard tool boundary for agent frameworks or assistants that already speak MCP.
+
+Use direct RedisVL client code when your application should own index lifecycle, search construction, data loading, or richer RedisVL features directly in Python.
+
+RedisVL MCP is a good fit when:
+
+- multiple assistants should share one approved retrieval surface
+- you want search behavior fixed by deployment config
+- you need a read-only or tightly controlled write boundary
+- you want to reuse an existing Redis index without rebuilding retrieval logic in every client
+
+For setup steps, config, commands, and examples, see {doc}`/user_guide/how_to_guides/mcp`.

docs/user_guide/how_to_guides/index.md

@@ -39,6 +39,7 @@ How-to guides are **task-oriented** recipes that help you accomplish specific go
 :::{grid-item-card} 💻 CLI Operations
 
 - [Manage Indices with the CLI](../cli.ipynb) -- create, inspect, and delete indices from your terminal
+- [Run RedisVL MCP](mcp.md) -- expose an existing Redis index to MCP clients
 :::
 
 ::::
@@ -59,6 +60,7 @@ How-to guides are **task-oriented** recipes that help you accomplish specific go
 | Optimize index performance | [Optimize Indexes with SVS-VAMANA](../09_svs_vamana.ipynb) |
 | Decide on storage format | [Choose a Storage Type](../05_hash_vs_json.ipynb) |
 | Manage indices from terminal | [Manage Indices with the CLI](../cli.ipynb) |
+| Expose an index through MCP | [Run RedisVL MCP](mcp.md) |
 
 ```{toctree}
 :hidden:
@@ -74,4 +76,5 @@ Optimize Indexes with SVS-VAMANA <../09_svs_vamana>
 Cache Embeddings <../10_embeddings_cache>
 Use Advanced Query Types <../11_advanced_queries>
 Write SQL Queries for Redis <../12_sql_to_redis_queries>
+Run RedisVL MCP <mcp>
 ```