feat(mcp): support multiple active index bindings (RAAE-1604)

[vishal-bala]

Motivation

The RedisVL MCP server currently binds to exactly one Redis index per process. That single-binding assumption is enforced by a config validator and baked throughout the codebase — single-resource server state, single-binding convenience accessors on MCPConfig, and the search/upsert tools. Before the server can expose multiple logical indexes from a single endpoint (RAAE-1603), that assumption has to be removed and replaced with a real multi-binding model.

This PR (RAAE-1604) does exactly that, and nothing more: it reshapes the configuration and runtime model so the server can start, inspect, validate, and serve one or many bindings, while keeping existing single-index configs and callers behaving identically. It is the foundation the rest of the epic (discovery via list-indexes, index routing on search-records/upsert-records, docs) builds on, so it intentionally does not yet add any new request parameters or tools.

Implementation

The core of the change is a new immutable BindingRuntime (in redisvl/mcp/runtime.py) that bundles everything a tool call needs for one logical index: the binding config, the connected AsyncSearchIndex, its effective (inspected + overridden) schema, an optional vectorizer, the resolved native-hybrid-search capability, and the effective read-only flag. The server now holds a dict[str, BindingRuntime] keyed by logical id instead of a single set of _index/_vectorizer fields. Startup iterates every configured binding and inspects, validates, and initializes each one independently — each binding owns its own Redis client — with all-or-nothing teardown so a single bad binding fails startup cleanly without leaking connections.

On the config side, the "exactly one configured index binding" validator is gone (we now simply require at least one binding with non-blank ids), and the schema-inspection, runtime-mapping, and search-validation methods move from MCPConfig onto MCPIndexBindingConfig where they naturally belong per binding. The single-binding convenience accessors on MCPConfig are removed. Each binding gains optional description and read_only fields, and a binding's effective write availability is computed as global --read-only OR the per-index read_only. Tool resolution goes through a new server.resolve_binding(index_id) helper that defaults to the sole binding when one is configured (preserving backward compatibility) and returns an invalid_request error when an index is omitted with multiple bindings configured or when an unknown id is given. The search and upsert tools were re-threaded to operate on a resolved BindingRuntime rather than reaching into single-binding server accessors.

Additional notes:

• Native-hybrid-search support is now probed eagerly per binding at startup and stored on the BindingRuntime, replacing the previous lazy single-index cache.
• The concurrency semaphore is a single process-wide ceiling sized from the maximum max_concurrency across bindings; the request timeout is sourced per-binding and passed explicitly into run_guarded.
• get_index() / get_vectorizer() are retained as thin convenience wrappers over resolve_binding(None).
• Implemented test-first: new coverage for multi-binding config loading, description/read_only defaults, resolve_binding routing semantics, semaphore sizing, per-binding teardown, and three integration tests (multi-binding startup, global read-only override, and a single invalid binding failing startup), alongside the updated single-index tests that confirm backward compatibility.

Verification

• mypy clean across all source files; black/isort formatted.
• 182 MCP unit tests pass.
• 44 MCP integration tests pass (2 skipped on Redis-version gates) against Redis 8.

🤖 Generated with Claude Code

---

Note

Medium Risk
MCP startup/teardown and binding resolution affect how indexes are served; the required run_guarded(..., timeout_seconds=) change breaks custom MCP extensions that call it directly.

Overview
MCP moves from a single enforced index binding to a dict of BindingRuntime entries: startup inspects and initializes each configured index independently (own client, vectorizer, hybrid probe, effective read-only), with resolve_binding(index_id) defaulting when only one index is configured and rejecting ambiguous or unknown ids. Config drops the “exactly one binding” rule and MCPConfig convenience accessors; per-binding description, read_only, and schema/search helpers live on MCPIndexBindingConfig. Search/upsert tools read from the resolved runtime; run_guarded now requires timeout_seconds= per binding (breaking for direct callers).

Also in this release: SearchIndex.drop_keys uses UNLINK instead of DEL; semantic router delete() removes the standalone route-config key; sql-redis>=0.7.1 with docs for hybrid_vector_search / FT.HYBRID; auto-release publishes to PyPI via pypa/gh-action-pypi-publish with OIDC; version 0.22.0.

^{Reviewed by Cursor Bugbot for commit bd2a28a. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

⚠️ Breaking change for downstream authors

RedisVLMCPServer.run_guarded(operation_name, awaitable) now requires a keyword-only timeout_seconds argument (sourced from each binding's request_timeout_seconds). Any code that subclasses RedisVLMCPServer or calls run_guarded directly (custom tools/plugins) must update its call sites to pass timeout_seconds=, otherwise it raises TypeError: run_guarded() missing 1 required keyword-only argument: 'timeout_seconds' at call time. This repository has no CHANGELOG file, so this note serves as the migration callout (per review feedback on #629).

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[vishal-bala]

CI is failing because of flaky tests that will be fixed by redis-developer/sql-redis#39

[nkanu17]

I really like the design!

Binding runtime dataclass is nice and like how resolve binding works as the single routing entry point shared across all tools keeps the behavior consistent and how it's backward compatible for single binding servers works

One blocking issue before merge:

the teardown loop in _teardown_runtime does not protect subsequent bindings if _close_resources raises on an earlier one.

• A failed disconnect on binding 1 will propagate out of the loop immediately, leaving bindings 2 through N with open Redis connections that are never closed.
• In a partial startup failure this is exactly the path that gets exercised, so the leak is not hypothetical.
• Wrapping each iteration in a try/except that logs and continues is a small fix and should be done before this lands.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3e441b2. Configure here.}

[nkanu17]

Thank you for the changes! Looks good! 🚀