9. 连接远程 MCP 客户端当服务器以 Streamable HTTP 或 SSE 方式运行时您需要在 MCP 客户端配置中指定服务器 URL。Streamable HTTPhttp://host:port/mcpSSEhttp://host:port/sse其中host和port应与服务器启动参数一致。若服务器绑定0.0.0.0客户端需使用机器的实际 IP 或域名并确保该主机名在 Host 白名单中。示例Claude Desktop 配置{mcpServers:{redisvl:{url:http://192.168.1.10:8000/mcp,transport:streamable-http}}}10. 工具合同Tool ContractsRedisVL MCP 向客户端暴露三个核心工具以下是每个工具的请求/响应格式及行为说明。10.1list-indexes发现可用索引无参数返回所有配置的逻辑索引及其元数据。响应示例{indexes:[{id:knowledge,description:内部运行手册,upsert_available:true,fields:[{name:title,type:text},{name:category,type:tag},{name:rating,type:numeric}],limits:{max_limit:25}}]}fields仅列出可用于过滤的字段标签、数值、地理等不含向量字段和用于嵌入的文本源字段。limits仅显示显式配置的运行时限制默认值不输出。底层的 Redis 索引名redis_name不会暴露给客户端。10.2search-records执行检索参数类型必填说明indexstring多索引时必填逻辑索引 ID单索引时可省略querystring是检索词向量搜索时为文本纯向量也可为空但一般使用查询文本limitinteger否返回结果条数默认使用配置的default_limitoffsetinteger否分页偏移默认为 0filterstring/object否过滤条件可为 Redis 原生过滤字符串或 JSON DSL 对象return_fieldsarray否指定返回的字段列表默认返回所有非向量字段请求示例JSON DSL 过滤器{index:knowledge,query:incident response,limit:2,filter:{and:[{field:category,op:eq,value:operations},{field:rating,op:gte,value:4}]},return_fields:[title,content]}响应示例{index:knowledge,search_type:hybrid,offset:0,limit:2,results:[{id:knowledge:doc-123,score:0.82,score_type:hybrid_score,record:{title:EU failover runbook,content:Restore traffic after a regional failover.,category:operations,rating:5}}]}search_type为响应元数据反映配置的检索类型。返回的record中不包含向量字段为节约带宽和安全性。如果请求的offset limit超出max_result_window请求会被拒绝。10.3upsert-records写入或更新记录参数类型必填说明indexstring多索引时必填逻辑索引 IDrecordsarray是要写入的记录对象列表id_fieldstring否记录中用作文档 ID 的字段名默认使用随机 IDskip_embedding_if_presentboolean否是否跳过已有向量的重新生成默认使用配置值请求示例{index:knowledge,records:[{doc_id:doc-42,content:Updated operational guidance,category:operations,rating:5}],id_field:doc_id}响应{index:knowledge,status:success,keys_upserted:1,keys:[knowledge:doc-42]}如果索引配置了vectorizer且记录中不包含向量字段服务器会使用default_embed_text_field指定的源字段生成向量。如果记录中已包含向量字段且skip_embedding_if_present为true则直接写入原向量。若目标索引为只读全局或单索引写入请求会被拒绝。11. 搜索与写入实战示例11.1 多索引时的发现‑检索流程在拥有多个索引的服务器上客户端应首先调用list-indexes获取可用 ID然后针对特定 ID 执行操作// 第一步列出索引// 请求list-indexes 无参// 响应中包含 knowledge 和 tickets// 第二步在 knowledge 中搜索{index:knowledge,query:cache invalidation,limit:3,return_fields:[title,content]}11.2 纯向量检索当search.type为vector时只需提供查询文本服务器会自动向量化并执行 KNN 搜索{query:cache invalidation incident,limit:3,return_fields:[title,content]}11.3 混合检索带权重配置在配置中设置search.type: hybrid并指定combination_method: LINEAR及linear_text_weight: 0.3则最终得分 0.3文本得分 0.7向量得分。客户端请求与向量检索类似但响应中的score_type会显示hybrid_score。11.4 过滤器使用原始字符串过滤器直接传递 Redis 查询语法{query:science,filter:category:{science},return_fields:[content,category]}JSON DSL 过滤器更结构化支持and/or/not及字段操作{query:science,filter:{and:[{field:category,op:eq,value:science},{field:rating,op:gte,value:4}]}}11.5 分页与字段投影通过limit和offset实现分页return_fields精确控制返回内容{query:science,limit:1,offset:1,return_fields:[content,category]}12. 写入Upsert进阶12.1 自动生成向量Server‑side Embedding当记录中缺少向量字段时服务器自动调用配置的向量化器将default_embed_text_field指定字段的文本转为向量并写入{records:[{content:First document,category:science,rating:5}]}12.2 使用id_field更新现有文档若id_field指定的值在 Redis 中已存在则该记录会被更新否则创建新文档{records:[{doc_id:doc-1,content:Updated content,category:engineering}],id_field:doc_id}12.3 控制向量重新生成skip_embedding_if_present: true默认若记录中已包含vector_field_name字段则直接使用该向量不重新生成。skip_embedding_if_present: false无论记录中是否有向量都强制重新生成覆盖原有向量。通常推荐让服务器管理向量客户端只需提供源文本避免传输大型向量。12.4 纯文本索引的写入如果索引只配置了全文检索无vectorizer和vector_field_name则upsert-records仅写入文本字段无需关心向量{records:[{content:New FAQ entry,category:support}]}13. 故障排查指南问题现象可能原因解决方案rvl mcp命令报缺少依赖未安装 MCP 额外依赖执行pip install redisvl[mcp]启动失败提示“Redis index does not exist”配置的redis_name在 Redis 中不存在先在 Redis 中创建该索引使用 RedisVL 或FT.CREATE启动失败提示环境变量缺失YAML 中使用了${VAR}但未定义设置对应环境变量或使用${VAR:-default}提供默认值启动失败提示向量维度不匹配向量化模型输出维度与schema_overrides或 Redis 索引中的维度不一致检查模型维度如text-embedding-3-small为 1536并修正配置HTTP 请求被拒绝403Host/Origin 校验未通过检查是否添加了客户端实际使用的域名到allowed_hosts或allowed_origins远程客户端连接不上绑定了127.0.0.1或端口被防火墙拦截使用--host 0.0.0.0并确保防火墙放行同时正确配置 Host 白名单upsert-records返回forbidden目标索引设置了read_only: true或全局--read-only检查配置若非必要请移除只读限制混合检索结果不符合预期可能缺少原生混合检索支持旧版 Redis升级 Redis 和 redis-py或移除不支持的参数如knn_ef_runtime14. 总结配置先行在启动服务器前确保所有索引已在 Redis 中创建且字段名称与配置完全匹配。单索引 vs 多索引单索引配置最简洁客户端无需指定index多索引适合为不同业务场景如知识库、工单提供统一接入但客户端需先调用list-indexes进行发现。安全生产环境绝对不要使用--allow-unauthenticated绑定到公网接口。请启用 JWT 认证并通过环境变量或配置文件严格限制 Host/Origin。向量化成本若向量化服务如 OpenAI按量计费请在runtime中合理设置skip_embedding_if_present避免重复生成同时限制max_upsert_records防止批量写入产生高昂费用。分页与性能通过max_result_window限制深度翻页避免大偏移量查询拖垮 Redis。max_limit和max_upsert_records则防止单次请求数据量过大。附录服务器启动流程图任一失败全部通过启动 rvl mcp解析 CLI 参数与环境变量加载 YAML 配置文件遍历 indexes 逐个验证启动失败记录错误初始化索引管理器、向量化器、工具注册表设置传输层stdio/HTTP/SSE配置传输安全Host/Origin/JWT绑定地址并开始监听服务器就绪等待 MCP 请求通过以上步骤能够顺利部署并运行 RedisVL MCP 服务器将 Redis 的强大检索能力以标准化工具的形式提供给您的智能体或应用。