Building the Redis Docs MCP: Technical Architecture for Agentic Documentation Retrieval

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 eliminate this systemic drift between released software defaults and agent knowledge, Redis engineered 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. By implementing one standard protocol contract, Redis Docs MCP provides instant integration for Claude, Codex, Cursor, and ChatGPT Deep Research without requiring vendor-specific bespoke connectors. 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"
    }
  }
}

Upon receiving this call, the MCP server responds with structured result data containing candidate documentation pages, their permanent stable keys, and associated text excerpts:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Results: [{\"id\": \"docs/manual/eviction\", \"title\": \"Key Eviction\", \"url\": \"https://redis.io/docs/latest/develop/reference/eviction/\", \"text\": \"Redis 8 changed several defaults regarding eviction configuration...\"}]"
      }
    ]
  }
}

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. This isolation guarantees high availability: should an upstream language model or intermediate gateway suffer downtime, automated systems can still search and fetch documentation uninterrupted.

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. Specifically, auditing the citation pipeline led to a redesign of how ask assembles source provenance, restricting the model from fabricating non-existent citation anchors during synthesis.

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.

Client Resilience in Python Workflows

While Docs MCP equips agents with documentation knowledge, operational application resilience against infrastructure failures relies on client-side connection management. As explained in Stay up when a region goes down: Highly available Redis for Python apps, client-side geographic failover can be handled by MultiDBClient, a wrapper provided in the redis-py ecosystem for single and cluster endpoints.

In multi-region setups, Active-Active Redis uses conflict-free replicated data types (CRDTs) to reconcile concurrent regional updates asynchronously. MultiDBClient routes traffic to an active database endpoint while continuously monitoring alternative regional configurations. If the primary instance degrades, an internal circuit breaker trips, causing the client to select another healthy endpoint based on assigned weights. Traffic can later revert automatically via background evaluations when the primary recovers, or failback can be disabled by setting auto_fallback_interval to -1 and invoking set_active_database().

Failure detection couples background health-check probes with a reactive FailureDetector that monitors successes and failures inside a sliding window. Health evaluation policies accommodate different availability profiles:

• HEALTHY_ALL: Demands that every probe succeed; suited for environments where sending traffic to an unstable node carries higher risk than an unnecessary failover.
• HEALTHY_ANY: Considers an endpoint healthy if at least one probe succeeds, minimizing false-positive failovers.
• HEALTHY_MAJORITY: Requires more than half of the probes to succeed, offering a balanced standard for production workloads.

When observability is enabled, MultiDBClient tracks failover transitions by recording the redis.client.geofailover.failovers counter, populating attributes including db.client.geofailover.fail_from, db.client.geofailover.fail_to, and db.client.geofailover.reason.