用途
该技能把智能体当前配置的多个 MCP 服务器统一放到一个 Redis Iris Context Gateway 之后,让智能体改为连接单个 MCP 端点并使用单个 agent key。智能体原有的工具保留不变,改变的只是工具访问路径。整体流程为:先询问、再配置、最后重新指向。
主要能力
- 托管每个上游服务器的密钥。
- 为工具名添加命名空间,避免不同上游之间的名称冲突。
- 当工具目录较大时,以 search_tools 和 run_tool 替代暴露全部 schema。
- 对经确认的只读工具进行缓存。
- 对过大的结果以句柄形式返回。
- 支持以 JSON 输出、无交互方式运行 CLI。
使用方式
-
发现阶段:阅读项目,找出智能体配置的所有 MCP 服务器(如 .mcp.json、.cursor/mcp.json、McpToolset、MCPServerStreamableHttp、MultiServerMCPClient、stdio_client 或手写 MCP 客户端),记录各端点及其密钥来源;找出工具交给模型的位置和回合执行位置;通过导入判断框架及其是否自带 MCP 客户端;注记仅支持 stdio 的服务器,因为上游必须是 HTTP MCP 端点(streamable-http),stdio 服务器需先以 HTTP 提供或留在 Gateway 之外。
-
确认 Gateway 运行位置:Redis Cloud(在控制台创建 Gateway 和上游,CLI 只连接 Gateway 的 MCP 端点;云环境关闭缓存与压缩)或自管理(本地 Compose 栈或本地部署,由 CLI 完成全部配置)。
-
向开发者询问五个问题(不确定时采用默认值):
- 智能体使用哪些 MCP 服务器、密钥存放在哪里:每个 HTTP 端点建立一个上游,使用
upstream add --name NAME --endpoint URL并配合--bearer-secret env:VAR或--header NAME --header-secret env:VAR;若为智能体应查询的 Redis 数据库,则使用 Context Surface 上游并先编写数据模型。 - 智能体总共看到多少工具:数十个用
--tool-exposure-mode full;数百个或 schema 占用提示词过多时用--tool-exposure-mode search。 - 哪些只读工具对相同参数返回相同结果:对相关工具设置
--cache-ttl策略,需要 Gateway 启用缓存和数据库。 - 哪些工具返回结果过大:启用压缩和不淘汰(noeviction)数据库,配置句柄默认值或
--compression-ttl,对必须始终返回完整结果的工具使用--compression-capture never。 - 框架是否自行连接 MCP 服务器:是(如 Claude Code、Cursor、ADK、OpenAI Agents SDK、LangChain MCP 适配器)则将其 MCP 客户端指向 Gateway URL 和 key;否则使用 SDK 的
gateway.model_tools()或gateway.hooks()。
- 智能体使用哪些 MCP 服务器、密钥存放在哪里:每个 HTTP 端点建立一个上游,使用
-
在写代码前从 MCP 获取当前事实:查询框架文档 MCP 了解所安装版本的 MCP 客户端如何接收 streamable HTTP URL 和 Authorization 头;如已连接 Redis 文档 MCP,可查询 Context Gateway 概念(上游、暴露模式、缓存、句柄)。无 MCP 可用时阅读虚拟环境中已安装包的源码,并在报告中说明。
-
安装 CLI:
pip install redis-iris,需要 Python 3.11 或更高版本;在 LangGraph 上安装redis-iris[langgraph]。 -
配置:
- Redis Cloud:目前无 Gateway 配置 API,控制平面仅接受控制台会话,云配置会以 cloud_unsupported 拒绝 service、upstream 和 policy 命令。开发者需在控制台创建 Gateway、添加上游或创建 Context Surface,然后在连接步骤复制 MCP 端点并创建 agent key,放入智能体环境或 .env 的
IRIS_CONTEXT_GATEWAY_URL和IRIS_CONTEXT_GATEWAY_API_KEY。密钥由开发者设置,绝不在对话中索取,也不要 echo、cat 或 grep 环境文件。将两个变量名以空值加入 .env.example,且不要提交 .env。云环境不启用缓存和压缩。 - 自管理:由人员导出
IRIS_CONTEXT_GATEWAY_SERVICE_URL、IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN、IRIS_IDENTITY_URL和IRIS_IDENTITY_TOKEN。本地 Compose 栈可在命令后加--local提供 service URL 和 token,但 Identity URL 仍需IRIS_IDENTITY_URL。Identity token 的取值顺序为--identity-token、IRIS_CONTEXT_GATEWAY_IDENTITY_TOKEN、IRIS_IDENTITY_TOKEN,最后是产品服务 token(仅当两者为同一密钥时有效)。可使用iris --json --no-input context-gateway service list、service create --name support --tool-exposure-mode full --write-env .env、service check <gatewayId>。Gateway CLI 只从环境读取IRIS_CONTEXT_GATEWAY_API_KEY,不读 .env。
- Redis Cloud:目前无 Gateway 配置 API,控制平面仅接受控制台会话,云配置会以 cloud_unsupported 拒绝 service、upstream 和 policy 命令。开发者需在控制台创建 Gateway、添加上游或创建 Context Surface,然后在连接步骤复制 MCP 端点并创建 agent key,放入智能体环境或 .env 的
-
Gateway 开关与数据库:每个 Gateway 有缓存和压缩两个开关(ENABLED 或 DISABLED),可用
service show查看。缓存禁用时--cache-ttl策略会返回 400;压缩关闭时压缩策略会被存储但不生效。两者还依赖运维方的部署开关。带数据库创建时两个开关均为 ENABLED;不带数据库时均为 DISABLED;数据库不支持压缩且未指定压缩时,缓存启用、压缩存储为禁用。缓存只对可缓存工具(未标记 readOnlyHint: false 或 destructiveHint: true)且设置了策略时生效。压缩需要 Gateway 数据库使用 noeviction 策略并安装 JSON 模块。缓存和句柄共用数据库,各自有 maxmemory 份额(默认 0.5 和 0.4,合计最多 0.95)。可用service diagnose --metrics-url查看计数。自管理时数据库来自部署配置,不从 CLI 指定。 -
以智能体方式运行 CLI:始终在产品名之前加
--json --no-input。先读后写,先运行service list。始终用--write-env PATH传递密钥。遇到 configuration_error、unauthenticated 或 forbidden 时停止并告知人员需设置哪个变量。上游密钥仅以引用方式传入:env:NAME、file:PATH或-。遇到 resource_exists 时询问是否用--reuse details.gatewayId或换名,绝不删除重试。每个错误为 stderr 上的单个 JSON 值,带 error.code,按错误码分派处理。--write-env .env会写入IRIS_CONTEXT_GATEWAY_URL、IRIS_CONTEXT_GATEWAY_ID和IRIS_CONTEXT_GATEWAY_API_KEY,同样三个名称以空值加入 .env.example。 -
添加上游:
iris --json --no-input context-gateway --gateway-id <gw_...> upstream add --name CRM --endpoint https://crm.example.com/mcp --bearer-secret env:CRM_TOKEN,或使用--header X-Api-Key --header-secret env:TICKETS_KEY,随后可用upstream tools crm查看。upstream add即使打印 initialCatalogFailure 也已完成创建:422 表示凭据被拒(用 upstream update 修复后再 upstream refresh),424 表示发现失败(检查控制平面能否访问端点),408 表示超时。Context Surface 上游的 422 表示 Surface 数据库拒绝了控制平面登录,424 表示工具生成失败(如 Redis NOPERM),均需在部署配置中修复后再 upstream refresh。 -
编写数据模型:Context Surface 上游需要数据模型 JSON,说明智能体可读取哪些记录以及如何索引;Gateway 据此生成工具,因此需在
upstream add --kind context-surface之前编写。模型层级包括 Model(title、description、entities[])、Entity(name、description、redis_key_template、relationships[]、fields[]、可选 document_type)、Field(name、type、description、is_key_component、redis_indices[]、标签可选 allowed_values)、Relationship(name、target、description、source_field)。规则:键模板中每个 {placeholder} 必须是 is_key_component: true 的字段,键字段不带索引;第一个占位符之前的文本必须……(资料在此处截断)。
适用场景
已有智能体通过多个 MCP 服务器接入工具,希望统一端点、集中管理密钥、避免工具名冲突、精简提示词中的工具 schema、缓存只读查询,或处理超大返回结果时。
限制
- 需要 Python 3.11 及以上的 redis-iris。
- Redis Cloud 暂无 Gateway 配置 API,需在控制台手工完成。
- 上游必须是 HTTP MCP 端点(streamable-http),stdio 服务器需先转为 HTTP 或留在 Gateway 之外。
- 缓存和压缩需要对应的 Gateway 开关和运维部署开关,压缩还要求 noeviction 数据库与 JSON 模块。
- 云环境不启用缓存和压缩。
- 数据模型规则部分资料不完整,相关细节暂未提供。