docs(mcp): document multi-index server contract (RAAE-1608)

Update the MCP concept doc, how-to guide, and README MCP section to reflect
formal multi-index support. Replace single-index-only language ("one server
binds to exactly one index") with the compatibility story: a single configured
index remains the simplest deployment and behaves unchanged, while multiple
indexes are formally supported behind discovery and explicit routing.

Document the list-indexes discovery tool and recommend clients call it first on
a multi-index server, then pass the chosen logical id as the index argument to
search-records and upsert-records. Explain that both tools echo the resolved
index, that an omitted index is valid only on single-index servers, and that
unknown ids fail with invalid_request.

Explain the two-level write policy: global --read-only disables writes across
every binding, while per-index read_only disables a single binding; upsert is
exposed only when at least one binding is writable, and writes to a read-only
binding are rejected with invalid_request. Clarify that list-indexes shares the
filterable fields discovered from each index, omits the vector and embed-source
fields, surfaces only explicitly configured runtime limits, and never exposes
redis_name.

- Add a two-binding config example (writable vector index + read-only fulltext
  index) and a list-indexes response example.
- Add index-parameterized search-records and upsert-records request/response
  examples and a discovery-first multi-index flow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vishal-bala

README.md

@@ -35,7 +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* |
+|  |  | **[MCP Server](#mcp-server)**<br/>*Expose one or more existing Redis indexes to MCP clients* |
 
 </div>
 
@@ -51,7 +51,7 @@ Install `redisvl` into your Python (>=3.10) environment using `pip`:
 pip install redisvl
 ```
 
-Install the MCP server extra when you want to expose an existing Redis index through MCP:
+Install the MCP server extra when you want to expose one or more existing Redis indexes through MCP:
 
 ```bash
 pip install redisvl[mcp]
@@ -572,16 +572,18 @@ Use `--read-only` to expose search without upsert.
 
 ### 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.
+RedisVL includes an MCP server that lets MCP-compatible clients search or upsert data in one or more existing Redis indexes 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`
+- connects to one or more existing Redis Search indexes, each addressed by a logical id
+- reconstructs each index's schema from Redis at startup
+- uses each index's configured vectorizer for query embedding and optional upsert embedding
+- exposes `list-indexes` for discovery, `search-records`, and (unless every index is read-only) `upsert-records`
 - supports stdio (default), Streamable HTTP, and SSE transports
 
+A single configured index is the simplest case and works exactly as before — callers omit the index selector. With multiple indexes, clients call `list-indexes` first and pass the chosen `index` to `search-records` and `upsert-records`.
+
 Run it over stdio (default):
 
 ```bash

docs/concepts/mcp.md

@@ -7,28 +7,30 @@ myst:
 
 # 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.
+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 one or more existing Redis indexes 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.
+1. It connects to one or more existing Redis Search indexes.
+2. It inspects each index at startup and reconstructs its schema.
 3. It initializes vector capabilities only when the configured search or upsert behavior needs them.
-4. It exposes stable MCP tools for search, and optionally upsert.
+4. It exposes stable MCP tools for discovery, search, and optionally upsert.
 
-This keeps the Redis index as the source of truth for search behavior while giving MCP clients a predictable interface.
+This keeps each Redis index as the source of truth for its 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.
+- One server process binds to one *or several* existing Redis indexes, each addressed by a logical id.
 - The server supports stdio (default), Streamable HTTP, and SSE transports.
-- Search behavior is owned by configuration, not by MCP callers.
-- Vector search and server-side embedding are optional capabilities configured explicitly.
-- Upsert is optional and can be disabled with read-only mode.
+- Search behavior is owned by per-index configuration, not by MCP callers.
+- Vector search and server-side embedding are optional capabilities configured explicitly per index.
+- Upsert is optional and can be disabled globally with read-only mode or per index with a `read_only` flag.
+
+A single-index server remains the simplest deployment: when exactly one index is configured, callers can omit the index selector entirely and every tool call targets that index. Multi-index support is fully formal — it adds discovery and explicit routing without changing the single-index contract.
 
 ## Config-Owned Search Behavior
 
@@ -44,17 +46,30 @@ These request-time controls are still bounded by runtime config. In particular,
 deep paging is limited by a configured maximum result window, enforced as
 `offset + limit`.
 
-MCP callers do not choose:
+On a multi-index server, callers also choose **which index to target** through an optional `index` argument (see [Index Selection](#index-selection-and-discovery)). 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.
+That behavior lives in the per-index server config under `indexes.<id>.search`. The response includes `search_type` as informational metadata, but it is not a request parameter.
+
+## Single and Multiple Index Bindings
+
+The YAML config uses an `indexes` mapping. Each entry is a logical binding keyed by an id (for example `knowledge` or `tickets`) that points to an existing Redis index through `redis_name`. The mapping may contain one entry or several; each binding is inspected, validated, and given its own search config, runtime limits, and optional vectorizer independently at startup. Startup is all-or-nothing — if any binding fails to initialize, the server does not start.
+
+A single-binding config is the simplest case and behaves exactly as before: the lone binding is the implicit target of every call. With multiple bindings the server stays a single process and endpoint, but callers select a binding per call.
+
+## Index Selection and Discovery
+
+On a multi-index server, every tool call must say which logical index it targets:
 
-## Single Index Binding
+- `search-records` and `upsert-records` accept an optional `index` argument naming the logical id.
+- When exactly one index is configured, `index` may be omitted and resolves to that sole binding (backward compatible).
+- When multiple indexes are configured, omitting `index` is an `invalid_request`; the caller must name one.
+- An unknown logical id is an `invalid_request`.
+- Both tools echo the resolved `index` in their response so clients can confirm routing.
 
-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.
+Because a client cannot guess the configured logical ids, multi-index servers expose a `list-indexes` discovery tool. **Clients should call `list-indexes` first** to enumerate the available indexes and their filterable fields, then pass the chosen id as `index` on subsequent calls.
 
 ## Schema Inspection and Overrides
 
@@ -71,14 +86,16 @@ MCP-reserved score metadata field names for the configured search mode.
 
 ## Read-Only and Read-Write Modes
 
-RedisVL MCP always registers `search-records`.
+RedisVL MCP always registers `search-records` and `list-indexes`.
 
-`upsert-records` is only registered when the server is not in read-only mode. Read-only mode is controlled by:
+Write availability is enforced at two levels:
 
-- the CLI flag `--read-only`
-- or the environment variable `REDISVL_MCP_READ_ONLY=true`
+- **Global read-only mode** disables writes across every binding. It is controlled by the CLI flag `--read-only` or the environment variable `REDISVL_MCP_READ_ONLY=true`.
+- **Per-index read-only** disables writes for a single binding via `indexes.<id>.read_only: true`, while other bindings stay writable.
 
-Use read-only mode when Redis is serving approved content to assistants and another system owns ingestion.
+These combine into each binding's *effective* write availability: a binding is read-only if global read-only is on **or** that binding sets `read_only: true`. The `upsert-records` tool is registered only when at least one binding is writable, so a fully read-only server does not advertise it at all. When the tool is registered, a write to a read-only binding is rejected with `invalid_request` before any data is changed. `list-indexes` reports each binding's effective write availability as `upsert_available`.
+
+Use read-only mode when Redis is serving approved content to assistants and another system owns ingestion — globally when no binding should accept writes, or per index when only some indexes are writable.
 
 ## Authentication and Authorization
 
@@ -88,18 +105,36 @@ For configuration and the gateway boundary, see {doc}`/user_guide/how_to_guides/
 
 ## Tool Surface
 
-RedisVL MCP exposes two tools:
+RedisVL MCP exposes up to three tools:
 
-- `search-records` searches the configured index using the server-owned search mode
-- `upsert-records` validates and upserts records, embedding them only when that capability is configured
+- `list-indexes` enumerates the configured logical indexes for discovery (always available)
+- `search-records` searches a selected index using that index's server-owned search mode
+- `upsert-records` validates and upserts records into a selected writable index, embedding them only when that capability is configured
 
 These tools follow a stable contract:
 
 - request validation happens before query or write execution
+- the resolved logical `index` is echoed in every `search-records` and `upsert-records` response
 - filters support either raw strings or a RedisVL-backed JSON DSL
-- `search-records` describes the inspected schema by advertising typed JSON DSL filter fields, object-filter `exists` support, and valid `return_fields`
+- on a single-index server, `search-records` describes the inspected schema by advertising typed JSON DSL filter fields, object-filter `exists` support, and valid `return_fields`; on a multi-index server those hints are ambiguous, so the description instead directs clients to call `list-indexes` and pass `index`
 - error codes are mapped into a stable set of MCP-facing categories
 
+### `list-indexes`
+
+`list-indexes` returns one entry per configured binding so clients can route subsequent calls. Each entry reports:
+
+- the logical `id`
+- an optional `description` (only when configured)
+- `upsert_available`, reflecting the binding's effective write availability
+- `fields`, the filterable fields discovered from the index
+- `limits`, only the runtime limits that were explicitly configured
+
+The discovery payload is deliberately minimal:
+
+- the underlying Redis index name (`redis_name`) is **never** exposed
+- the vector field and the configured embed-source text field are **omitted** from `fields`, since they are implementation inputs rather than fields a client filters on
+- `limits` shows only explicitly set values (such as `max_limit` or `max_upsert_records`); defaults are not echoed
+
 ## 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.