本文将逐步完成 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 扩展：

pip install redisvl[mcp]

若您需要使用特定的向量化提供商（例如 OpenAI），请同时安装对应的额外依赖：

pip install redisvl[mcp,openai]

提示：如果仅进行纯文本检索（fulltext），则无需安装任何向量化依赖。

---

5. 启动服务器

RedisVL MCP 提供了三种传输方式，以适应不同的调用场景：

5.1 stdio（默认，适用于本地 MCP 客户端）

uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml

这是最常见的启动方式，MCP 客户端会通过标准输入/输出与服务器通信，适合与本地智能体（如 Claude Desktop）集成。

5.2 Streamable HTTP（适用于远程客户端）

uvx --from redisvl[mcp] rvl mcp \
  --config /path/to/mcp.yaml \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allow-unauthenticated

安全警告：绑定到 0.0.0.0 会监听所有网络接口，必须明确设置 --allow-unauthenticated 或启用 JWT 认证，否则服务器拒绝启动。生产环境强烈建议启用认证（见下文“安全”章节）。

5.3 SSE（Server-Sent Events）

uvx --from redisvl[mcp] rvl mcp \
  --config /path/to/mcp.yaml \
  --transport sse \
  --host 0.0.0.0 \
  --port 9000 \
  --allow-unauthenticated

SSE 适用于需要服务器主动推送事件的客户端，但 MCP 核心交互仍以请求‑响应为主。

5.4 只读模式

若您希望客户端只能执行搜索，不能写入数据，可使用 --read-only 标志：

uvx --from redisvl[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: false

indexes:
  # 每个索引由一个逻辑 ID 标识
  <logical-id>:
    redis_name: <existing-index-name>   # 必须与 Redis 中已有索引名称一致
    description: "可选描述"              # 会通过 list-indexes 返回给客户端
    read_only: false                    # 若为 true，该索引禁止写入（即使全局未只读）
    vectorizer:                         # 向量化配置（可选）
      class: OpenAITextVectorizer       # 支持的类名
      model: text-embedding-3-small
      api_config:
        api_key: ${OPENAI_API_KEY}
    schema_overrides:                   # 用于覆盖从 Redis 自动探测的字段属性
      fields:
        - name: embedding
          type: vector
          attrs:
            dims: 1536
            datatype: float32
    search:
      type: hybrid                      # fulltext / vector / hybrid
      params:
        text_scorer: BM25STD
        stopwords: english
        vector_search_method: KNN
        combination_method: LINEAR
        linear_text_weight: 0.3
    runtime:                            # 运行时行为调优
      text_field_name: content          # 全文检索的目标字段
      vector_field_name: embedding      # 向量检索的目标字段
      default_embed_text_field: content # 写入时用于生成向量的源字段
      default_limit: 10
      max_limit: 25
      max_result_window: 1000
      max_upsert_records: 64
      skip_embedding_if_present: true
      startup_timeout_seconds: 30
      request_timeout_seconds: 60
      max_concurrency: 16

7.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: knowledge
    description: "内部运行手册与操作指南"
    vectorizer:
      class: OpenAITextVectorizer
      model: text-embedding-3-small
      api_config:
        api_key: ${OPENAI_API_KEY}
    search:
      type: vector
    runtime:
      text_field_name: content
      vector_field_name: embedding
      default_embed_text_field: content
      default_limit: 10
      max_limit: 25

  tickets:
    redis_name: support-tickets
    description: "已解决的支持工单（只读镜像）"
    read_only: true
    search:
      type: fulltext
      params:
        text_scorer: BM25STD
        stopwords: english
    runtime:
      text_field_name: body
      default_limit: 10
      max_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 工具根本不会被注册。

---