Redis Docs MCP at redis.io/mcp: search, fetch and ask Tools

Bridging the Knowledge Gap for Coding Agents #

When an autonomous coding agent is prompted to configure key eviction in Redis 8, it frequently provides an outdated answer derived from Redis 7 configuration directives. Because Redis 8 changed several defaults, language models relying strictly on baseline pretraining data or unstructured web scraping often deliver obsolete recommendations with complete confidence. General web search engines return search hits without stable identifiers, preventing an agent from reliably citing what it examined or retrieving the same context on subsequent turns. Conversely, client-side retrieval forces external developer frameworks to continually re-implement chunking, vector embedding, and corpus freshness against documentation they do not own or maintain.

To give agents the current documentation, Redis built a dedicated Model Context Protocol endpoint at redis.io/mcp. As documented in How we built the Redis Docs MCP for agents, four engineers built the server across one quarter, spanning April to July 2026. The implementation serves three specific tools—search, fetch, and ask—over the official documentation index without requiring user authentication. By offering an unauthenticated surface, the architecture gives automated tooling a direct pipeline to authoritative documentation pages while preserving caller privacy and reducing protocol friction.

Tool Contract and JSON-RPC Interface #

The Model Context Protocol establishes an open client-server interface that enables language models to discover and invoke tools dynamically. In the team's words, one MCP contract reaches Claude, Codex, Cursor and ChatGPT Deep Research without shipping four integrations. The server exposes exactly three tools over a single endpoint accepting JSON-RPC POST /mcp requests:

• search(query): Returns up to eight matching pages. Each match includes a snippet, a title, a URL, and a stable identifier. This is the intended default starting point for any general Redis inquiry.
• fetch(id): Takes a stable page identifier and returns full markdown text along with metadata covering topic, version, and section. Clients reach for this tool when a snippet is insufficient or when verbatim quoting is required.
• ask(question): Synthesizes a prose answer accompanied by source documents, specifically designed for multi-topic queries where no single page supplies the complete answer.

Restricting the interface strictly to three tools represents a deliberate architectural constraint. Because MCP transmits tool signatures and docstrings during the initial connection handshake, every additional tool description consumes context window tokens on every query turn, regardless of whether that tool is ever invoked. Keeping the count small minimizes prompt bloat across long agent sessions.

Furthermore, the search and fetch interfaces deliberately adopt the conventions established by OpenAI for documentation MCP servers, such as naming the snippet property text rather than content. This precise parameter alignment allows connectors like ChatGPT Deep Research to query the documentation with zero custom adapter code on either side of the wire.

The following sketch illustrates an MCP JSON-RPC tool invocation requesting documentation search results over the JSON-RPC interface:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "configure eviction redis 8"
    }
  }
}

Bifurcated Retrieval Paths: Direct Query Engine vs. Gateway Synthesis #

Behind the single JSON-RPC entry point, the backend decouples retrieval paths into two distinct execution strategies: a direct data path for search and fetch, and a managed gateway path for ask.

The direct path bypasses language models entirely. Both search and fetch issue commands directly against the Redis Query Engine using RedisVL. For search, the application generates native FT.HYBRID queries against the docs index. Because the engineers own the raw query pipeline, they executed sweeps across four distinct retrieval parameters: the target text field, the scoring algorithm, the hybrid fusion method, and candidate result counts. The post gives the reason for the direct path as "owning the query is what lets us tune it". Hybrid search with the title field and RRF fusion raised Hit@3 by 0.08 and recall@8 by 0.06 over vector-only search, at 0.5 to 0.7 ms p50 and under 1.3 ms p95 measured locally, while Hit@1 fell by 0.04.

The ask tool, in contrast, executes through Context Retriever—a Redis product that ingests an entity schema, provisions a managed retrieval surface over a database, and exposes retrieval tools to an agent over MCP. In late April 2026, the team spent three weeks building a grounded chat assistant on the Context Retriever marketing page, producing a FastAPI service streaming server-sent events that went live in early June 2026. The ask tool bundles this synthesis pipeline as an embedded shared library rather than invoking an external HTTP service. Within this tool, an internal language model holds generated Context Retriever tools and iteratively selects which retrieval steps to run before delivering a prose response. The model drives retrieval actively rather than acting as a simple post-hoc summarizer.

Index Lifecycle and Single-Writer Hygiene #

Maintaining data integrity across two parallel reader systems requires a strict single-writer architecture. The documentation index is written exclusively by a headless ingest pipeline that processes Hugo markdown files directly from the redis/docs GitHub repository. During ingestion, the pipeline strips front matter and template shortcodes, segments long pages into chunks along secondary ## heading boundaries, generates vector embeddings, and writes the resulting objects to Redis through Context Retriever.

Neither the public Docs MCP server nor the marketing demo service holds administrative rights over index creation, schema definition, or embedding generation. In production, the Docs MCP application discovers the index dynamically at startup rather than relying on a hardcoded index name in environment variables. To guarantee numerical vector compatibility, the ingestion pipeline and the search path import identical constants for EMBEDDING_MODEL and EMBEDDING_DIM.

Spec-Driven Engineering and Citation Verification #

Managing asynchronous engineering work across both human developers and coding agents required a disciplined spec-driven workflow. Rather than jumping straight into code changes, the team authored approximately thirty specification documents inside a tracked spec/ directory. These files covered architecture proposals, interface contracts, design reviews, and working notes.

Every specification document maintained a fixed repository location and exposed a dedicated status line rather than shifting between folders during lifecycle transitions, preserving permanent reference URLs. Writing out interfaces comprehensively before delegating implementation minimized drift when coding agents generated pull requests. One redesign changed how ask cites sources: instead of letting the model write URLs, which once produced a citation that resolved to nothing, ask now returns a sources array derived from what the retrieval pipeline actually fetched. Every id comes from a real tool call, so a fabricated id cannot appear, and every id resolves through fetch.

Keyless Access and Operational Security Controls #

Opting for a keyless, unauthenticated deployment aligns with serving both open-source developers and enterprise customers without imposing registration hurdles. However, operating an open public endpoint enforces distinct privacy and security boundaries:

• Per-caller raw request text is never written to persistent logs.
• Telemetry collection is restricted strictly to aggregate metrics.
• Internal ranking scores and internal non-fetchable identifiers are stripped before crossing the wire.
• Because all three MCP operations enter through an identical HTTP route via POST /mcp, the hosting edge cannot differentiate between search and ask by URL path alone. Per-tool rate limiting is consequently enforced inside the application layer by inspecting the JSON-RPC payload.

Separate Redis Post: Regional Failover in redis-py #

An unrelated Redis post from September, Stay up when a region goes down: Highly available Redis for Python apps, covers client-side failover rather than documentation: MultiDBClient in redis-py routes traffic to an active database, trips a circuit breaker when it degrades and switches to another healthy endpoint by weight. It has nothing to do with Docs MCP.