add-context-gateway

Context Gatewayを追加する

現在エージェントが設定しているMCPサーバーをすべて、1つのMCPエンドポイントと1つのエージェントキーに置き換えます。Gatewayは各Upstreamのシークレットを保持し、ツール名に名前空間を付けて重複を防ぎます。また、大規模なカタログをすべてのスキーマではなくsearch_toolsとrun_toolとして公開でき、オプトインした読み取り専用ツールをキャッシュし、大きな結果をハンドルとして返すこともできます。エージェントのツールはそのままで、接続先だけが変わります。まず質問し、プロビジョニングしてから、接続先を切り替えます。

1. 調査する

プロジェクトを確認します。

• エージェントが設定しているすべてのMCPサーバーを見つけます。.mcp.json、.cursor/mcp.json、McpToolset、MCPServerStreamableHttp、MultiServerMCPClient、stdio_client、または手書きのMCPクライアントを確認します。各エンドポイントとシークレットの取得元を記録します。
• ツールをモデルに渡している場所と、ターンを実行している場所を見つけます。
• インポートからフレームワークを特定し、そのフレームワーク独自のMCPクライアントがあるかどうかを確認します。
• stdioのみのサーバーを記録します。UpstreamはHTTP MCPエンドポイント（streamable-http）です。stdioサーバーは、先にHTTP経由で提供するか、Gatewayの対象外とする必要があります。

まずGatewayの実行場所を確認します。

• Redis Cloud（コンソール）。 開発者がコンソールでGatewayとUpstreamを作成し、CLIはGatewayのMCPエンドポイントとのみ通信します（ステップ3「Redis Cloudの場合」）。CloudではGatewayのキャッシュと圧縮が無効になっているため、質問3と4は省略します。
• セルフマネージド（オンプレミス、またはローカルComposeスタック）。CLIですべてをプロビジョニングします（ステップ3）。

次に、開発者に以下の5つの質問だけをします。それ以上は質問しません。回答に迷った場合は、デフォルトを選びます。

質問	回答	設定
エージェントはどのMCPサーバーを使用し、シークレットはどこにありますか？	HTTPエンドポイントのリスト	Upstreamごとに1つ設定します。upstream add --name NAME --endpoint URLに--bearer-secret env:VARまたは--header NAME --header-secret env:VARを指定します
	エージェントがクエリするRedisデータベース	Context Surface Upstream：--kind context-surface --surface-database-id ID --data-model FILE（セルフマネージドではIDを省略でき、デプロイ設定の値がデフォルトになります。Redis Cloudでは、コンソールの「Create Context Surface」でデータベースを指定します）。先にデータモデルを記述します。「データモデルを記述する」を参照してください
エージェントが認識するツールの総数はどれくらいですか？	数十個（デフォルト）	--tool-exposure-mode full：すべてのツールに名前空間を付けます
	数百個、またはスキーマがプロンプトを圧迫する	--tool-exposure-mode search：モデルにはsearch_toolsとrun_toolを表示します
同じ引数に対して同じ回答を返す読み取り専用ツールはどれですか？	ルックアップ、検索、参照データ	データベースとcacheを有効にしたGatewayを設定します（「Gatewayのスイッチとデータベース」を参照）。次に、ツールごとにpolicy set UPSTREAM TOOL --cache-ttl DURATIONを設定します
	なし、または不明	キャッシュポリシーは設定しません
結果が大きすぎて全体を読み取れないツールはどれですか？	エクスポート、リストエンドポイント、ログ	noevictionデータベースとcompressionを有効にしたGatewayを設定します（「Gatewayのスイッチとデータベース」を参照）。次に、デプロイのハンドルのデフォルトを使用するか、ツールごとに--compression-ttl DURATIONを設定します。結果全体を常に返す必要があるツールには--compression-capture neverを設定します
フレームワークはMCPサーバーに直接接続しますか？	はい：Claude Code、Cursor、ADK、OpenAI Agents SDK、LangChain MCP adapters	MCPクライアントの接続先をGatewayのURLとキーに変更します
	いいえ、またはエージェントが通常の関数ツールを使う場合	SDKを使います：gateway.model_tools()またはgateway.hooks()

2. MCPから最新の情報を取得する

コードを書く前に実行します。フレームワークのAPIを記憶だけで推測してはいけません。

• フレームワークのドキュメント：利用可能なドキュメントMCP（Context7またはフレームワーク独自のもの）に、インストール済みバージョンのMCPクライアントについて問い合わせます。streamable HTTP URLとAuthorizationヘッダーの指定方法を確認します。
• Redisのドキュメント：RedisのドキュメントMCPに接続されている場合は、Context Gatewayの概念（Upstreams、公開モード、キャッシュ、ハンドル）について問い合わせます。
• MCPが利用できない場合：仮想環境内のインストール済みパッケージのソースを読みます。その旨をレポートに記載します。

3. プロビジョニングする

CLI をインストールする

pip install redis-iris

Python 3.11 以降が必要です。LangGraph では、redis-iris[langgraph] をインストールしてください。Gateway ID が設定されている（--gateway-id または IRIS_CONTEXT_GATEWAY_ID）検索モードの Gateway で tools call crm__lookup_customer が tool_not_found で失敗する場合、インストール済みのリリースではツール名が最初の . で分割されています。redis-iris をアップグレードするか、IRIS_CONTEXT_GATEWAY_URL を設定して Gateway ID を指定せずに tools call を実行すると、CLI が search_tools を通じて名前を解決します。

Redis Cloud の場合

Redis Cloud には、まだ Gateway をセットアップする API がありません。コントロールプレーンが受け取るのはコンソールセッションのみであるため、cloud プロファイルでは service、upstream、policy コマンドが cloud_unsupported を返し、エージェントはプロビジョニングできません。開発者がコンソールで設定します。

1. Iris → Context Gateway：Gateway を作成するか、既存の Gateway を開きます。
2. Gateway の Upstreams で、質問 1 にある各 HTTP サーバーに対して Add MCP server を選択するか、Redis データベースに対して Create Context Surface を選択します（先にデータモデルを記述してください。「データモデルを記述する」を参照）。
3. 接続手順で MCP エンドポイントをコピーし、エージェントキーを作成します。
4. エージェントの環境または .env にある IRIS_CONTEXT_GATEWAY_URL と IRIS_CONTEXT_GATEWAY_API_KEY に値を設定します。設定するのは開発者であり、エージェントではありません。チャットでキーを尋ねたり、環境ファイルを表示するために echo、cat、grep を実行したりしないでください。

両方の名前を空の値で .env.example に追加し、.env は絶対にコミットしないでください。その後、この手順の残りをスキップして手順 4 に進みます。Cloud ではキャッシュと圧縮が無効になっているため、設定するポリシーやハンドルはありません。

セルフマネージド環境の場合

IRIS_CONTEXT_GATEWAY_SERVICE_URL、IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN、IRIS_IDENTITY_URL、IRIS_IDENTITY_TOKEN をエクスポートしてもらいます。ローカルの Compose スタックでは、コマンドの後に --local を付けると（service list --local）、サービスの URL とトークンが設定されますが、Identity URL は設定されないため、create には引き続き IRIS_IDENTITY_URL が必要です。

Identity トークン。 各製品のチャートで、それぞれ独自の Identity Service を実行できます。その場合は、製品固有の IRIS_CONTEXT_GATEWAY_IDENTITY_TOKEN（および IRIS_CONTEXT_GATEWAY_IDENTITY_URL またはプロファイルの identity_url）を設定し、IRIS_IDENTITY_URL は未設定のままにしてください。これはプロファイル内のすべての製品の identity_url を上書きするためです。1 つの Identity Service を共有するスイートでは、IRIS_IDENTITY_TOKEN と IRIS_IDENTITY_URL ですべての製品に対応できます。CLI はトークンを --identity-token、IRIS_CONTEXT_GATEWAY_IDENTITY_TOKEN、IRIS_IDENTITY_TOKEN、製品のサービス トークンの順に取得します。最後のトークンが使えるのは、2 つのシークレットが同じ場合に限られます。

iris --json --no-input context-gateway service list
iris --json --no-input context-gateway service create --name support --tool-exposure-mode full --write-env .env
set -a; . ./.env; set +a; iris --json --no-input context-gateway service check <gatewayId from the result>

Gateway CLI は環境からのみ IRIS_CONTEXT_GATEWAY_API_KEY を読み込み、.env からは読み込みません。そのため、キーがコマンドの環境に設定されるまでは、service check、tools、handle は configuration_error で失敗します。上記のように同じシェルコマンド内でファイルを読み込むか（または uv run --env-file .env iris ... を使用して）、キーが出力に含まれないようにしてください。

Gateway のスイッチとデータベース

各 Gateway には cache と compression の 2 つのスイッチがあり、それぞれ ENABLED または DISABLED になります。service show gw_0123456789abcdef0123456789abcdef で両方を確認できます。Gateway の cache が DISABLED の場合、--cache-ttl ポリシーは 400 エラーで拒否されるため、先に cache を有効にしてください。圧縮ポリシーは保存されますが、compression がオフの場合は機能しません。どちらの機能にも、オペレーターのデプロイメントスイッチ（データプレーン設定の cache.enabled と compression.enabled。デフォルトではオフ）も必要です。

作成	cache と compression
データベースあり：--database-id ID、またはオンプレミスのデフォルト defaultDatabases.gatewayDb	両方とも ENABLED
データベースなし	両方とも DISABLED。データベースがない状態で ENABLED を送信すると、そのフィールドで 400 エラーになります
圧縮を利用できない（下記を参照）、または到達不能なデータベースがあり、compression を省略した場合	cache は ENABLED、compression は DISABLED として保存
機能	動作する条件
---	---
キャッシュ	Gateway の cache が ENABLED であり、ツールがキャッシュ可能で（readOnlyHint: false または destructiveHint: true の指定がなく、ヒントがないツールも対象となるため、読み取り専用と分かっているツールだけをオプトインしてください）、--cache-ttl ポリシーが設定されている
圧縮	Gateway の compression が ENABLED であり、ツールのポリシーが --compression-capture never ではない

service create と service update では、--cache enabled|disabled と --compression enabled|disabled をどちらの大文字・小文字でも指定でき、API には大文字の値が送信されます。フラグを省略すると、サーバーのデフォルト値または既存の値がそのまま維持されます。後からデータベースを追加しても、どちらの機能も有効にならないため、明示的に有効にしてください。

iris --json --no-input context-gateway service update gw_0123456789abcdef0123456789abcdef --database-id gateway-db --cache enabled --compression enabled

データベースを切り離すには、1 回の更新で --clear-database --cache disabled --compression disabled を指定します。古い --expected-revision を指定すると、412 revision_conflict が返されます。再試行するかどうかを決める前に、リソースを読み直してください。

データベースの要件：

• 圧縮には、maxmemory-policy noeviction と JSON モジュールを備えた Gateway データベースが必要です。別のポリシーで圧縮を有効にすると（作成時、更新時、または有効のまま databaseId を変更した場合）、/compression を示す errors[] エントリとともに 400 が返されます。理由は database lru-db uses allkeys-lru, compression needs noeviction のようになります。compression enabled を送信したときにデータベースに到達できない場合は 503 が返されるため、再試行してください。適さない、または到達できないデータベースに対して compression を省略して作成した場合は拒否されません。代わりに compression は DISABLED として保存されるため、service show で読み戻してください。
• キャッシュのみの場合、どの Gateway データベースでも動作します。ハンドルとキャッシュエントリでデータベースを共有するため、maxmemory に十分な余裕を持たせてください。追い出しポリシーが設定されたキャッシュ専用データベースでは、Redis がエントリを追い出すため、以下の共有上限は適用されません。
• ハンドルとキャッシュには、それぞれ独自の maxmemory 割り当てがあります。 ハンドルは compression.max_memory_share（デフォルトは 0.5）まで、キャッシュは cache.max_memory_share（デフォルトは 0.4）まで使用できます。合計の上限は 0.95 で、互いの割り当てを消費することはありません。どちらも maxmemory の 90％を超えると停止しますが、これは共有割り当てで対処できない場合の最後の安全策にすぎません。
• ハンドルの割り当てがいっぱいになると、 自動キャプチャでは結果全体が返され、明示的な run_tool_as_handle ではツールエラー handle storage is full, release handles or narrow the query が返されます。キャッシュの割り当てがいっぱいの場合は、書き込みが省略され、結果が返されます。ハンドルを解放すると、その割り当てはすぐに空きます。期限切れのハンドルも約 10 秒以内に空きます。
• TTL に合わせて Gateway データベースのサイズを決めてください。 ハンドルとキャッシュエントリは TTL が切れるまで保持されます（ハンドルのデフォルトは 15 分）。そのため、それぞれの割り当てには 1 秒あたりの作成数 x TTL x 保存サイズ 分の容量が必要です。保存サイズを結果サイズから推測しないでください。実測してください。service diagnose --metrics-url ではキャッシュと圧縮のカウンターが表示され、skipped_low_memory または out_of_memory の発生が増えている場合は、その側の容量がいっぱいであることを示します。収まらない場合は、--compression-ttl または --cache-ttl を短くするか、maxmemory またはオペレーターの共有割り当てを増やしてください。
• オンプレミス環境では、 データベースはデプロイ設定から取得され、CLI からは取得されません。shared.config.databases で各 ID を登録し、databaseConnections で URL を指定し、defaultDatabases.gatewayDb と defaultDatabases.surfaceDb でデフォルトを選択します。ID が見つからない場合は、オペレーターに問い合わせてください。圧縮が有効な場合は、Gateway データベースと Surface データベースを別々の Redis インスタンスにしてください。そうしないと、noeviction が顧客データにも適用されます。

service diagnose gw_0123456789abcdef0123456789abcdef を実行すると、Gateway のデータベース（no Gateway database は、すべての呼び出しでキャッシュがバイパスされることを意味します）、各 Upstream のカタログ、キャッシュポリシーが表示されます。--metrics-url を追加すると、キャッシュと圧縮のカウンターが表示されます。eviction_policy、skipped_low_memory、または out_of_memory の発生が増えている場合は、ハンドルが保持されていないことを示します。

エージェントとして CLI を実行する

1. 製品名の前に必ず --json --no-input を指定してください。stdout には JSON 値が 1 つ、stderr にはエラーが JSON 値で 1 つ出力され、プロンプトは表示されません。
2. 書き込む前に読み取ってください。service create には --dry-run がないため、最初に service list を実行してください。サービスの URL とトークンを確認できます。そこで configuration_error、unauthenticated、または forbidden が発生した場合は、何も作成する前にステップ 4 に従って担当者に引き継いでください。
3. キーは必ず --write-env PATH（または service key では --write PATH）を指定して書き出してください。--json を指定してファイルを指定せずに create や key を実行しないでください。キーが実行履歴に出力されてしまいます。
4. configuration_error、unauthenticated、または forbidden が発生したら、停止してください。設定すべき変数（メッセージ、または details.env に記載）を担当者に伝え、details.obtain がある場合はそのリンクを共有してください。チャットでシークレットを尋ねたり、コマンドラインで渡したり、環境変数ファイルを表示、cat、または grep したりしないでください。
5. 上流のシークレットは参照のみで渡してください。env:NAME、file:PATH、または - を使用します。担当者に変数をエクスポートするよう依頼し、シークレットを自分で書き込まないでください。
6. resource_exists が発生した場合は、details.gatewayId を --reuse で再利用するか、別の名前を選ぶか担当者に確認してください。再試行のために削除しないでください。create が details.created: true で失敗した場合は、--reuse --write-env を指定して再実行してください。

エラーはすべて、error.code を含む JSON 値 1 つとして stderr に出力されます。認証情報に関するエラーには details.env と details.obtain も含まれますが、値は含まれません。最初の失敗で停止し、その内容を伝えてください。

error.code	対応する人	対応
credential_required	担当者	エージェントのシェルで、details.env に記載された変数を設定してください。上記の「ID トークン」を参照してください。
unauthenticated	担当者	details.source のトークンが拒否されました。有効期限が切れているか、別のデプロイメントのトークンです。新しいトークンを発行してください。
forbidden	担当者	トークンは有効ですが、必要なロールまたはテナントがありません。その製品に適したロールを持つトークンを使用してください。
configuration_error	担当者またはエージェント	url などの URL が設定されていません。プロファイルに追加してください。
invalid_request	エージェント	HTTP 400 です。メッセージで指摘されているリクエストを修正してください。
resource_exists	担当者	--reuse を指定して再実行し、details.gatewayId を採用するか、別の名前を選んでください。
unavailable	担当者	ホップに到達できません。URL、イングレス、サービスの Pod を確認してください。
check_failed	担当者	details.hop と details.cause に問題のあるホップが示されています。修正してからチェックを再実行してください。
cloud_unsupported	担当者	プロファイルの kind = "cloud" が原因です。コンソールで details.steps に従ってください。
input_error、usage_error	エージェント	コマンドを修正してください。--no-input のもとで破壊的なコマンドを実行するには、担当者から --yes の指定を受ける必要があります。

--write-env .env を実行すると、IRIS_CONTEXT_GATEWAY_URL（Gateway の MCP エンドポイント）、IRIS_CONTEXT_GATEWAY_ID、IRIS_CONTEXT_GATEWAY_API_KEY が書き込まれます。同じ 3 つの名前を、値を空にして .env.example に追加してください。.env をコミットしないでください。

Upstream を追加します（質問 1）。IRIS_CONTEXT_GATEWAY_ID はシークレットではありません。create の出力にある gatewayId（gw_ に続く 32 桁の 16 進数）を --gateway-id で渡してください。

iris --json --no-input context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef upstream add --name CRM --endpoint https://crm.example.com/mcp --bearer-secret env:CRM_TOKEN
iris --json --no-input context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef upstream add --name Tickets --endpoint https://tickets.example.com/mcp --header X-Api-Key --header-secret env:TICKETS_KEY
iris --json --no-input context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef upstream tools crm

initialCatalogFailure が出力された場合でも、upstream add によって Upstream は作成されています。422 は Upstream が認証情報を拒否したことを示します（upstream update で修正し、その後 upstream refresh を実行してください）。424 は検出に失敗したことを示します（コントロールプレーンからエンドポイントに到達できるか確認してください）。408 はタイムアウトを示します。--kind context-surface の Upstream では、422 は Surface データベースがコントロールプレーンのログインを拒否したことを示し、424 はツールの生成に失敗したことを示します（例：Redis の NOPERM）。どちらもデプロイメント設定で修正してから、upstream refresh を実行してください。

データモデルを作成する

Context Surface Upstream には、エージェントが読み取れるレコードと、そのインデックス方法を示す JSON のデータモデルが必要です。Gateway はこれを基にツールを生成するため、upstream add --kind context-surface を実行する前に作成してください。

レベル	メンバー
Model	title、description、entities[]
Entity	name、description、redis_key_template（例：order:{id}、デフォルトは <Name>:{id}）、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 のフィールドにします。キー用フィールドにはインデックスを設定しません。最初のプレースホルダーより前のテキスト（order:）は、:, _, -, / または . で終わるリテラルにする必要があります。これがインデックスのプレフィックスになります。
• フィールドの type は str、int、float、bool、list[str]、list[float]、geo、timestamp または object です。object にはインデックスを設定できません。
• レコードはデフォルトで RedisJSON として保存されます。"document_type": "hash" を指定すると、エンティティは Hash として保存されます。この場合、object フィールドは使用できず、list[float] はベクトルインデックスがある場合に限り使用でき、キー用フィールドはスカラーである必要があります。
• Gateway は acl_field_mappings を 400 エラーで拒否するため、指定しないでください。Gateway へのアクセス権を持つすべてのエージェントキーは、Surface のすべてのレコードを読み取れます。iris リポジトリのサンプルファイルにはこれが含まれているため、そのファイルをコピーしないでください。

エージェントの検索方法に応じてインデックスを選択します。

インデックス	フィールドの型	用途	生成されるツール
tag	str、bool、list[str]	ステータス、ID、カテゴリなどの完全一致フィルター。allowed_values に有効な値を列挙します	filter_<entity>
text	str	名前、説明、メモの全文検索。weight でフィールドの順位を調整し、no_stem でステミングを無効にします	search_<entity>_by_text
numeric	int、float、timestamp	範囲検索と並べ替え。sortable: false を指定しない限り並べ替え可能です。list_ には並べ替え可能なフィールドが必要で、timestamp に sortable: false は指定できません	filter_<entity>、list_<entity>、summarize_<entity>
vector	list[float]	意味に基づく検索。vector_dim と distance_metric（cosine、euclidean、dot_product）、およびデータプレーン上の埋め込みサービスが必要です。Redis Cloud ではまだクエリを埋め込めないため、現時点ではこれらのツールは動作しません	埋め込み対象のテキストフィールドを source_field に指定した場合は search_<entity>_by_<field>_semantic、それ以外は _similarity。さらに、そのテキストフィールドに text インデックスがあり、Surface の Redis が RESP3 経由のネイティブなハイブリッド検索に対応している場合は、search_<entity>_by_<field>_hybrid（テキストとベクトルを組み合わせて順位付け）
geo	geo	半径内のレコード	find_<entity>_near_<field>

キーテンプレートにプレースホルダーが 1 つあるエンティティには、get_<entity>_by_id も生成されます。また、count_<entity> はレコード数をカウントします。エンティティをまたいで、セットツールの intersect_results、union_results、except_results、expand_results を使うと、フィルターを組み合わせたり、リレーションシップをたどったりできます。各ツールは読み取り専用で、<namespace>__<tool> の形式で表示されます。例：orders__search_order_by_text。ツールが必要とするフィールドがモデルにある場合にのみ、そのツールが生成されます。text インデックスがなければ、テキスト検索はできません。

最小限の orders モデル：

{
  "title": "Orders",
  "description": "Customer orders",
  "entities": [
    {
      "name": "Order",
      "description": "A customer order",
      "redis_key_template": "order:{id}",
      "relationships": [],
      "fields": [
        {"name": "id", "type": "str", "description": "Order ID", "is_key_component": true, "redis_indices": []},
        {"name": "status", "type": "str", "description": "open, shipped or cancelled", "redis_indices": [{"type": "tag"}]},
        {"name": "notes", "type": "str", "description": "Free-text order notes", "redis_indices": [{"type": "text", "weight": 1.0}]},
        {"name": "total", "type": "float", "description": "Order total in dollars", "redis_indices": [{"type": "numeric", "sortable": true}]}
      ]
    }
  ]
}

orders.json として保存し、--surface-database-id ID --data-model orders.json を指定して追加します。レコードは、これらのフィールド名を持つ JSON ドキュメントとして order:<id> に保存されます。upstream add の後、upstream tools orders を実行すると、生成されたツールを確認できます。Redis が既存のキーのインデックス作成を完了するまで（FT.INFO <index> で percent_indexed が 1 になるまで）、検索結果が不完全な場合があります。データモデルを変更（upstream update）するとインデックスが再作成されるため、データベースに余裕があるときに実行してください。

ポリシーを設定します（質問 3 と 4）。upstream tools にキャッシュ可能なツールが表示されます。--cache-ttl を指定できるのは、それらのツールだけです。

iris --json --no-input context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef policy set crm search_customers --cache-ttl 5m
iris --json --no-input context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef policy set crm export_orders --compression-ttl 1h

キーとシークレットのローテーション

• 新しいエージェントキー：service key gw_0123456789abcdef0123456789abcdef --write .env を実行するとキーが発行され、ファイルに追加または更新されます。エージェントを再起動して、新しい値を読み込ませてください。
• 同じ Gateway を使う2人目の開発者：service env gw_0123456789abcdef0123456789abcdef --write .env を実行すると、キーを発行せずに URL と ID が書き込まれます。その後、本人用のキーを service key で発行します。
• 新しい Upstream シークレット：担当者に新しい値を環境変数として設定してもらい、upstream update crm --bearer-secret env:CRM_TOKEN（または --header-secret）を実行してから、upstream refresh crm を実行します。

完全なリファレンス：iris context-gateway <command> --help（例：iris context-gateway upstream add --help）。

4. エージェントの接続先を変更する

MCP ネイティブフレームワーク（質問5への回答が「はい」の場合）。各サーバーの設定を Gateway の設定1つに置き換えます。connect は、実行時に変数から読み込んだキーを使って設定を書き込みます。キーが出力されることはありません。Redis Cloud では、cloud プロファイルを指定し、--gateway-id を付けずに connect を実行します。エンドポイントは IRIS_CONTEXT_GATEWAY_URL から取得されます。

iris context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef connect --client claude-code --write .mcp.json
iris context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef connect --client cursor --write .cursor/mcp.json
iris context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef connect --client adk > gateway_tools.py
iris context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef connect --client json

別の MCP クライアント（OpenAI Agents SDK、LangChain MCP アダプター）では、json 出力を使用します。URL、streamable-http、および IRIS_CONTEXT_GATEWAY_API_KEY の値を使った Authorization: Bearer ヘッダーを指定します。手順2でクライアントのパラメーター名を確認してください。.env ファイルの内容は実行中のクライアントには反映されません。変数は、クライアントの起動時に使われる環境に設定する必要があります。

SDK ツール（質問5への回答が「いいえ」の場合）：

from redis_iris import ContextGateway

gateway = ContextGateway.from_env()
tools = gateway.model_tools()  # framework-free Tool objects, one per Gateway tool

TypeScript エージェントについては、@redis-iris/context-gateway APIを参照してください。

LangGraph では、redis_iris.integrations.langgraph の langchain_tools(gateway.hooks()) を使うと、ToolNode 用の LangChain ツールを取得できます。Agent Memory または Agent Playbooks も接続している場合は、モデルが各製品のすべてのツールを1か所から利用できるよう、まとめて接続します。

from redis_iris.hooks import stack
from redis_iris.integrations.langgraph import attach, langchain_tools

hooks = stack(memory.hooks(), playbook.disclosure(), gateway.hooks())
graph.add_node("tools", ToolNode(langchain_tools(hooks)))
app = attach(hooks, graph).compile()

gateway.call("crm__lookup_customer", id="cust-1042") はツールを直接呼び出します（result.data、result.is_error）。gateway.call_as_handle(...) は大きな結果を Gateway 上に Handle として保持します。読み取りは Gateway 上で行います。gateway.page(handle, limit=5)、gateway.query(handle, ...)、count、aggregate、describe、gateway.release(handle) を使用できます。非同期版は atools、acall、apage などです。

次に、Gateway が置き換えた設定を削除します。各サーバーの MCP 設定、エージェントの環境にあるサーバーごとのシークレット（Gateway が保持するようになりました）、手作業で設定した名前空間やツールのフィルタリングを削除してください。

ツール名は namespace__tool 形式に変わります。たとえば、crm__lookup_customer です。ツール名を指定しているプロンプトのテキストやコードを更新してください。

検索モードでは、モデルが tools/list でこれらの名前を確認することはありません。query（および省略可能な limit。デフォルトは5）を指定して search_tools を呼び出すと、完全な MCP ツール定義が返されます。run_tool でツールを実行する際は、tool に検索結果の upstreamId と originalName を指定し、toolArgs に引数を指定します。プロンプトのテキストにはツール名ではなく、ツールが実行するタスクを記述してください。ツール名を指定して呼び出すコードは、SDK と CLI が namespace__tool を解決するため、そのまま動作します。

エージェント側のハンドル

Gateway の compression が有効な場合、tools/list には、どちらの公開モードでも 7 つのツール（run_tool_as_handle、describe_result、count_results、page_results、query_results、aggregate_results、release_results）が追加されます。ツールの結果が 32 KiB を超えると、全ペイロードの代わりに、プレビューと次の手順を含むハンドル（h_ と 32 桁の 16 進数）を保持した小さなスタブが返されます。フルモードでは、outputSchema を宣言したツールは結果全体を返します。--compression-capture never を指定したツールは結果全体を返し、そのツールに対する run_tool_as_handle は、エージェントにツールを直接呼び出すよう伝えるツールエラーになります。エージェントのプロンプトには、以下のツールを使ってハンドルを読み取り、全ペイロードを再度要求しないように指示してください。

エージェントの要望	呼び出すツール
サイズを問わず、複数回の後続処理に備えて大きな結果を保持する	run_tool_as_handle（フルモードでは name と toolArgs、検索モードでは tool と upstreamId、originalName、toolArgs）
ハンドルの形式、サイズ、フィールド、有効期限を確認する	describe_result
アイテム数、またはフィールドの値ごとの件数を確認する	jsonpath または groupBy を指定して count_results
数値の合計、最小値、最大値、平均値を確認する	jsonpath を指定して aggregate_results
条件に一致するアイテムのみを取得する	$[[email protected]=="open"] のような JSONPath を指定し、ページ分割して query_results
アイテムを順に読み取る、またはテキスト結果をバイト単位で読み取る	offset と limit を指定して page_results
メモリを早めに解放する	release_results

run_tool_as_handle が handle storage is full, release handles or narrow the query を返した場合、エージェントは不要になったハンドルに対して release_results を呼び出してから、クエリの範囲を絞って再試行するか、ツールを直接呼び出してください。

ハンドルはデプロイの TTL（デフォルトでは 15 分）またはツールの --compression-ttl が経過すると期限切れになります。読み取りによって有効期限が延長されることはありません。期限切れ、解放済み、または別のキーのハンドルは、理由 unknown_handle を含む Gateway の拒否になります。CLI の handle コマンドでは handle_not_found（終了コード 1）として報告されるため、新しいハンドルを取得するにはツールを再度呼び出してください。部分ハンドル（長い結果の 1 ページ分）は、completeness と warning でその旨が示されます。次のページを取得するには、ページング引数を指定して run_tool_as_handle を再度呼び出してください。Context Surface のキャプチャは、デプロイの上限（10,000 行）まで、すべてのページをそれ自体で読み取ります。そのため、大きな Surface クエリ 1 件でハンドルストレージがいっぱいになることがあります（既知の問題 MOD-20735）。圧縮が DISABLED の場合、tools/list から 7 つのツールがなくなります。SDK では、gateway.call_as_handle(...) が Handle を返し、redis_context_gateway.mcp.HANDLE_TOOLS に 7 つの名前が列挙されています。

5. 検証

チェック 1、3、4、6、7 では、コマンドの環境変数にエージェントキーが必要です。set -a; . ./.env; set +a; iris ... を 1 つのシェルコマンドとして実行し、ファイルの内容を表示してはいけません。

Redis Cloud では、3、4、8、9 を --gateway-id を付けずに実行します。tools コマンドは IRIS_CONTEXT_GATEWAY_URL とエージェントキーを使用します。それ以外のチェックはコントロールプレーンを呼び出すか、Cloud では提供されないキャッシュとハンドルを必要とします。

1. iris context-gateway service check gw_0123456789abcdef0123456789abcdef は、トークン、Gateway、Identity Service、エージェントキー、およびエージェントキーを使用した 1 回の tools/list のすべてのステップに合格します。
2. iris --json context-gateway service show gw_0123456789abcdef0123456789abcdef で、質問で求められているとおりに cache と compression が表示されます。使用中の各機能は ENABLED で、databaseBinding が存在します。エージェントが選択していない DISABLED は、データベースがないか、圧縮が拒否されたことを意味します（ステップ 3「Gateway のスイッチとデータベース」）。
3. iris context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef tools list で、すべての Upstream のツールが名前空間付きで（フルモード）、または search_tools と run_tool（検索モード）が表示されます。圧縮が有効な場合は、7 つのハンドルツールも一覧表示されます。
4. iris context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef tools call crm__lookup_customer --arg id=42 は、サーバーから返された内容をそのまま返します。
5. iris context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef policy list crm で、質問 3 と 4 のキャッシュポリシーと圧縮ポリシーが表示されます。
6. キャッシュヒット：キャッシュポリシーのツールを使い、iris --json context-gateway --gateway-id gw_0123456789abcdef0123456789abcdef tools call crm__search_customers --arg query=acme を 2 回実行します。2 回目の結果の _meta["com.redis.context-gateway/invocation"] には "cache": {"status": "hit", ...} が含まれ、1 回目には cache の項目がありません。
7. ハンドルの往復：tools call crm__export_orders --as-handle を実行すると h_... を含むスタブが出力され、その後の handle describe h_...、handle page h_... --limit 5、handle release h_... はそれぞれ応答します。解放済みのハンドルに対して 2 回目の handle describe を実行すると、handle_not_found とともに終了コード 1 で終了します。
8. Gateway ツールを使用するタスクでエージェントを 1 回実行し、その呼び出しが Gateway 経由で行われたことを（トレースまたはログの名前空間付きの名前で）示します。
9. IRIS_CONTEXT_GATEWAY_API_KEY を解除し、SDK がこの環境変数名を示す ConfigurationError を発生させること、または MCP クライアントが認証失敗を報告することを確認します。

iris context-gateway service diagnose gw_0123456789abcdef0123456789abcdef では、失敗している Upstream、キャッシュまたはハンドルの設定、および Gateway データベースの不足について説明されます。

6. 報告

Gateway の実行場所（Redis Cloud またはセルフマネージド）、5 つの回答、追加した各 Upstream（名前、名前空間、エンドポイント、シークレット変数名。値は記載しないでください）、公開モード、設定した各ポリシー、Gateway の cache と compression の値およびそれらの背後にあるデータベース、書き込んだデータモデル、変更したファイル、記述したクライアント設定、追加および削除した環境変数、検証結果、および MCP 経由で確認できなかった事項を記載します。