本文将逐步完成 RedisVL MCP 服务器的部署、配置和使用。将 Redis 索引无缝集成到 AI 智能体Agent工作流通过 MCP 协议暴露高性能的向量检索与全文检索能力。1. RedisVL MCPRedisVL MCP是一个基于 MCPModel Context Protocol的服务器实现。它允许客户端如 LLM 驱动的智能体、自定义应用程序通过标准化的 MCP 工具接口对已存在的 Redis 索引执行搜索向量检索、全文检索、混合检索和写入插入或更新文档记录。其核心设计理念是将 Redis 的检索能力抽象为可调用的“工具”使上层应用无需关心底层索引细节只需通过 JSON 请求即可完成复杂的检索与写入操作。MCP是一种轻量级、语言无关的通信协议旨在为 AI 模型提供统一的环境上下文访问接口。RedisVL MCP 实现了该协议的服务器端可运行于 stdio、Server-Sent Events (SSE) 或 Streamable HTTP 传输之上。2. 整体架构概览下图展示了 RedisVL MCP 的核心组件与交互流程RedisVL MCP 服务器ClientMCP 协议请求调用工具获取索引元数据执行搜索/写入向量化请求启动时加载配置安全策略操作索引Redis 实例索引 A已有索引 B已有MCP 客户端智能体/应用传输层stdio/SSE/HTTP请求路由器索引管理器工具注册表向量化引擎可选安全校验Host/Origin/JWT配置解析器YAML 环境变量传输层支持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 SSEServer-Sent Eventsuvx--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 格式--transportstdio传输协议stdio、sse、streamable-http--host127.0.0.1绑定地址仅用于 HTTP/SSE--port8000绑定端口仅用于 HTTP/SSE--read-onlyfalse全局禁用所有写入操作--allow-unauthenticated无仅用于 HTTP 传输表示允许未认证访问配合--host 0.0.0.0使用6.2 环境变量您可以通过环境变量覆盖部分启动行为方便容器化部署变量作用REDISVL_MCP_CONFIG配置文件的路径可代替--configREDISVL_MCP_READ_ONLY设为true等效于--read-onlyREDISVL_MCP_TOOL_SEARCH_DESCRIPTION覆盖search-records工具的描述文本高级定制REDISVL_MCP_TOOL_UPSERT_DESCRIPTION覆盖upsert-records工具的描述文本REDISVL_MCP_ALLOWED_HOSTSHTTP 传输中额外允许的 Host 头值逗号分隔REDISVL_MCP_ALLOWED_ORIGINSHTTP 传输中额外允许的 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 字段含义解析配置段关键字段说明serverredis_urlRedis 连接地址支持环境变量替换如${REDIS_URL}server.transport_securityallowed_hosts,allowed_originsHTTP 传输的安全校验白名单用于防止 DNS 重绑定攻击。若客户端通过代理访问可设置enabled: false或allow_any_origin: true。indexes.idredis_name必填对应 Redis 中已存在的索引名称description可选描述会通过list-indexes呈现给客户端帮助智能体选择合适的索引read_only为true时即便全局未开启只读该索引也拒绝写入vectorizer仅当需要进行向量化时才配置。class指定向量化器类型如OpenAITextVectorizermodel和api_key根据提供商填写。schema_overridesfields当 Redis 自动探测的字段属性如向量维度不完整时用于手动修正。通常用于向量字段。searchtype检索类型fulltext纯文本、vector纯向量、hybrid文本向量加权。params检索参数如文本评分器BM25STD、向量搜索方法KNN、混合权重等。不同检索类型需要的参数不同具体可参考 RedisVL 文档。runtimetext_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 传输特有当服务器通过 HTTPStreamable 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工具根本不会被注册。