【高速缓存】 RedisVL MCP 运行指南（上）
本文将逐步完成 RedisVL MCP 服务器的部署、配置和使用。将 Redis 索引无缝集成到 AI 智能体（Agent）工作流，通过 MCP 协议暴露高性能的向量检索与全文检索能力。
1. RedisVL MCP
RedisVL MCP是一个基于 MCP（Model Context Protocol）的服务器实现。它允许客户端（如 LLM 驱动的智能体、自定义应用程序）通过标准化的 MCP 工具接口，对已存在的 Redis 索引执行搜索（向量检索、全文检索、混合检索）和写入（插入或更新文档记录）。其核心设计理念是将 Redis 的检索能力抽象为可调用的“工具”，使上层应用无需关心底层索引细节，只需通过 JSON 请求即可完成复杂的检索与写入操作。
MCP是一种轻量级、语言无关的通信协议，旨在为 AI 模型提供统一的环境上下文访问接口。RedisVL MCP 实现了该协议的服务器端，可运行于 stdio、Server-Sent Events (SSE) 或 Streamable HTTP 传输之上。
2. 整体架构概览
下图展示了 RedisVL MCP 的核心组件与交互流程：
- 传输层：支持
stdio（本地进程通信）、SSE和Streamable HTTP（远程访问），灵活适配不同部署场景。 - 索引管理器：负责加载 YAML 配置中定义的多个索引绑定，验证其存在性及字段类型，并提供统一的检索/写入接口。
- 工具注册表：向客户端暴露
list‑indexes、search‑records、upsert‑records等工具，每个工具都有明确的输入输出契约。 - 向量化引擎：若配置了向量检索，则使用指定的向量化模型（如 OpenAI Embedding）将查询文本或写入记录的文本字段转为向量。
- 安全校验：对 HTTP 传输提供 Host/Origin 头校验，防止 DNS 重绑定攻击；并支持可选的 JWT 身份验证（生产级部署推荐）。
3. 前提条件
| 条件 | 说明 |
|---|---|
| Python 版本 | 3.10 或更新版本 |
| Redis 环境 | 已部署 Redis 且启用了 Search 能力（Redis Stack 或 Redis Enterprise with RediSearch 模块） |
| 目标索引 | 需要操作的 Redis 索引已经创建完成（服务器只负责接入，不负责创建） |
| 关键字段 | 明确知道该索引中用于全文检索的文本字段名（如content）以及向量字段名（如embedding，若涉及向量检索） |
| 向量化依赖 | 若使用向量检索，需根据选择的向量化服务（如 OpenAI、Cohere）安装对应的 Python 包 |
4. 安装 RedisVL MCP
通过pip安装主包及 MCP 扩展：
pipinstallredisvl[mcp]若您需要使用特定的向量化提供商（例如 OpenAI），请同时安装对应的额外依赖：
pipinstallredisvl[mcp,openai]提示：如果仅进行纯文本检索（fulltext），则无需安装任何向量化依赖。
5. 启动服务器
RedisVL MCP 提供了三种传输方式，以适应不同的调用场景：
5.1 stdio（默认，适用于本地 MCP 客户端）
uvx--fromredisvl[mcp]rvl mcp--config/path/to/mcp.yaml这是最常见的启动方式，MCP 客户端会通过标准输入/输出与服务器通信，适合与本地智能体（如 Claude Desktop）集成。
5.2 Streamable HTTP（适用于远程客户端）
uvx--fromredisvl[mcp]rvl mcp\--config/path/to/mcp.yaml\--transportstreamable-http\--host0.0.0.0\--port8000\--allow-unauthenticated安全警告：绑定到
0.0.0.0会监听所有网络接口，必须明确设置--allow-unauthenticated或启用 JWT 认证，否则服务器拒绝启动。生产环境强烈建议启用认证（见下文“安全”章节）。
5.3 SSE（Server-Sent Events）
uvx--fromredisvl[mcp]rvl mcp\--config/path/to/mcp.yaml\--transportsse\--host0.0.0.0\--port9000\--allow-unauthenticatedSSE 适用于需要服务器主动推送事件的客户端，但 MCP 核心交互仍以请求‑响应为主。
5.4 只读模式
若您希望客户端只能执行搜索，不能写入数据，可使用--read-only标志：
uvx--fromredisvl[mcp]rvl mcp--config/path/to/mcp.yaml --read-only这会让upsert‑records工具对所有索引均不可用（即使配置中未显式设置read_only）。
6. CLI 参数与环境变量速查
6.1 命令行参数
| 参数 | 默认值 | 说明 |
|---|---|---|
--config | （必填） | MCP 配置文件的路径（YAML 格式） |
--transport | stdio | 传输协议：stdio、sse、streamable-http |
--host | 127.0.0.1 | 绑定地址（仅用于 HTTP/SSE） |
--port | 8000 | 绑定端口（仅用于 HTTP/SSE） |
--read-only | false | 全局禁用所有写入操作 |
--allow-unauthenticated | 无 | 仅用于 HTTP 传输，表示允许未认证访问（配合--host 0.0.0.0使用） |
6.2 环境变量
您可以通过环境变量覆盖部分启动行为，方便容器化部署：
| 变量 | 作用 |
|---|---|
REDISVL_MCP_CONFIG | 配置文件的路径，可代替--config |
REDISVL_MCP_READ_ONLY | 设为true等效于--read-only |
REDISVL_MCP_TOOL_SEARCH_DESCRIPTION | 覆盖search-records工具的描述文本（高级定制） |
REDISVL_MCP_TOOL_UPSERT_DESCRIPTION | 覆盖upsert-records工具的描述文本 |
REDISVL_MCP_ALLOWED_HOSTS | HTTP 传输中额外允许的 Host 头值（逗号分隔） |
REDISVL_MCP_ALLOWED_ORIGINS | HTTP 传输中额外允许的 Origin 头值（逗号分隔） |
REDISVL_MCP_ALLOW_ANY_ORIGIN | 设为true则允许任意 Origin（用于受信任的反向代理环境） |
REDISVL_MCP_TRANSPORT_SECURITY_ENABLED | 设为false禁用 Host/Origin 校验（当上游代理已做验证时） |
7. 配置文件（YAML）详解
配置文件是 RedisVL MCP 的核心，它定义了服务器如何连接到 Redis、管理哪些索引、以及每个索引的检索与写入行为。
7.1 顶层结构
server:redis_url:${REDIS_URL}# Redis 连接字符串（支持环境变量替换）# 可选的传输安全配置transport_security:allowed_hosts:[mcp.example.com]allowed_origins:[https://app.example.com]# allow_any_origin: true# enabled: falseindexes:# 每个索引由一个逻辑 ID 标识<logical-id>:redis_name:<existing-index-name># 必须与 Redis 中已有索引名称一致description:"可选描述"# 会通过 list-indexes 返回给客户端read_only:false# 若为 true，该索引禁止写入（即使全局未只读）vectorizer:# 向量化配置（可选）class:OpenAITextVectorizer# 支持的类名model:text-embedding-3-smallapi_config:api_key:${OPENAI_API_KEY}schema_overrides:# 用于覆盖从 Redis 自动探测的字段属性fields:-name:embeddingtype:vectorattrs:dims:1536datatype:float32search:type:hybrid# fulltext / vector / hybridparams:text_scorer:BM25STDstopwords:englishvector_search_method:KNNcombination_method:LINEARlinear_text_weight:0.3runtime:# 运行时行为调优text_field_name:content# 全文检索的目标字段vector_field_name:embedding# 向量检索的目标字段default_embed_text_field:content# 写入时用于生成向量的源字段default_limit:10max_limit:25max_result_window:1000max_upsert_records:64skip_embedding_if_present:truestartup_timeout_seconds:30request_timeout_seconds:60max_concurrency:167.2 字段含义解析
| 配置段 | 关键字段 | 说明 |
|---|---|---|
| server | redis_url | Redis 连接地址，支持环境变量替换（如${REDIS_URL}） |
| server.transport_security | allowed_hosts,allowed_origins | HTTP 传输的安全校验白名单，用于防止 DNS 重绑定攻击。若客户端通过代理访问，可设置enabled: false或allow_any_origin: true。 |
| indexes.<id> | redis_name | 必填，对应 Redis 中已存在的索引名称 |
description | 可选描述，会通过list-indexes呈现给客户端，帮助智能体选择合适的索引 | |
read_only | 为true时，即便全局未开启只读，该索引也拒绝写入 | |
vectorizer | 仅当需要进行向量化时才配置。class指定向量化器类型（如OpenAITextVectorizer），model和api_key根据提供商填写。 | |
| schema_overrides | fields | 当 Redis 自动探测的字段属性（如向量维度）不完整时，用于手动修正。通常用于向量字段。 |
| search | type | 检索类型：fulltext（纯文本）、vector（纯向量）、hybrid（文本+向量加权）。 |
params | 检索参数，如文本评分器（BM25STD）、向量搜索方法（KNN）、混合权重等。不同检索类型需要的参数不同，具体可参考 RedisVL 文档。 | |
| runtime | text_field_name | 全文/混合检索必填，指定用于文本匹配的字段名。 |
vector_field_name | 向量/混合检索必填，指定存储向量的字段名。 | |
default_embed_text_field | 若需要在写入时自动生成向量，此字段指定用于生成向量的源文本字段。 | |
default_limit | 若客户端未指定limit，使用的默认值。 | |
max_limit | 客户端允许的最大limit值，防止一次返回过多数据。 | |
max_result_window | 分页时允许的最大offset + limit值，控制深度翻页的边界。 | |
max_upsert_records | 单次upsert-records请求允许的最大记录条数。 | |
skip_embedding_if_present | 若设为true，当记录中已包含向量字段时，不再重新生成向量（直接使用）；若为false，则强制重新生成。 | |
| 超时/并发 | startup_timeout_seconds、request_timeout_seconds、max_concurrency控制服务器内部资源。 |
7.3 多索引配置示例
您可以在indexes下定义多个逻辑 ID，每个指向不同的 Redis 索引，并拥有独立的检索和写入策略：
server:redis_url:${REDIS_URL}indexes:knowledge:redis_name:knowledgedescription:"内部运行手册与操作指南"vectorizer:class:OpenAITextVectorizermodel:text-embedding-3-smallapi_config:api_key:${OPENAI_API_KEY}search:type:vectorruntime:text_field_name:contentvector_field_name:embeddingdefault_embed_text_field:contentdefault_limit:10max_limit:25tickets:redis_name:support-ticketsdescription:"已解决的支持工单（只读镜像）"read_only:truesearch:type:fulltextparams:text_scorer:BM25STDstopwords:englishruntime:text_field_name:bodydefault_limit:10max_limit:50启动检查：服务器启动时会逐个验证每个索引配置是否有效（索引是否存在、字段是否正确等）。任一索引配置失败，整个服务器将拒绝启动，保证客户端不会遇到部分可用的混乱状态。
8. 安全机制详解
8.1 Host / Origin 校验（HTTP 传输特有）
当服务器通过 HTTP（Streamable HTTP 或 SSE）暴露时，默认会验证请求的Host和Origin头，以防止DNS 重绑定攻击。这种攻击可让恶意网页将自身域名解析到127.0.0.1，从而访问本机服务。
- Host 校验：服务器会根据绑定的地址自动派生允许的 Host 列表（如绑定
127.0.0.1则允许localhost、127.0.0.1、[::1]）。若客户端通过公共域名访问，您需要在配置或环境变量中额外添加该域名。 - Origin 校验：没有
Origin头的请求（如非浏览器客户端）直接放行；有Origin头的必须匹配白名单，否则拒绝。
您可以通过以下方式定制校验行为：
- 配置文件中的
server.transport_security块 - 环境变量
REDISVL_MCP_ALLOWED_HOSTS、REDISVL_MCP_ALLOWED_ORIGINS - 若前置的反向代理已做了充分验证，可设置
enabled: false或allow_any_origin: true来关闭校验。
8.2 JWT 身份验证（生产环境推荐）
对于生产部署，强烈建议启用 JWT 身份验证，而非依赖--allow-unauthenticated。启用后，客户端必须在请求头中携带有效 JWT 令牌，服务器才会处理工具调用。具体配置方式请参考官方文档中“Authenticate RedisVL MCP”章节。
关于
--read-only的补充：即使全局未只读，只要某个索引设置了read_only: true，针对该索引的upsert‑records请求会被直接拒绝。若所有索引均只读，则upsert‑records工具根本不会被注册。