{
"schema_version": 2,
"id": "develop/ai/context-engine/context-gateway/concepts",
"title": "Redis Context Gateway concepts",
"url": "https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/concepts/",
"summary": "Understand Gateways, Upstreams, credentials, tool exposure modes, the cache, compression, and agent access.",
"aliases": [
"/develop/ai/context-engine/context-retriever/concepts/"
],
"tags": [
"docs",
"develop",
"ai"
],
"last_updated": "2026-11-02T17:32:57-08:00",
"page_type": "content",
"content_hash": "0cde1e4c1cba8d814fa53e6863a92f53584fd1ab68d84c93ca2f0d1a677a2fcf",
"sections": [
{
"id": "overview",
"title": "Overview",
"role": "overview",
"text": "Redis Context Gateway gives agents access to tools from multiple sources through one Model Context Protocol (MCP) endpoint. You choose which sources to connect and whether agents receive all tool definitions or discover relevant tools as needed.\n\nThe Gateway also helps agents work efficiently with tool results. **Caching** reuses results for repeated calls, reducing requests to connected sources. **Compression** stores large results outside the agent’s context and lets the agent retrieve selected portions or calculate counts and aggregates.\n\nThis page explains how Gateways, tool sources, discovery modes, caching, and compression work together."
},
{
"id": "gateways",
"title": "Gateways and Upstreams",
"role": "content",
"text": "A **Gateway** brings together a set of tools that an agent or team needs. Each source of tools registered with a Gateway is an **Upstream**.\n\n\n\nContext Gateway supports two kinds of Upstream:\n\n| Source | What it provides |\n| --- | --- |\n| **MCP server** | Tools from a third-party or in-house server that supports Streamable HTTP. |\n| **Context Surface** | Tools generated from a data model describing records in a Redis database. |\n\nFor example, a support agent might need to look up invoices and search product information. You could register a billing MCP server and a product Context Surface with the same Gateway. The agent then accesses both through one connection.\n\n"
},
{
"id": "tool-names",
"title": "Tool names",
"role": "content",
"text": "Each Upstream has a **namespace** that distinguishes its tools from tools provided by other sources. For example, the `get_invoice` tool from an Upstream with the namespace `billing` appears as `billing__get_invoice`.\n\nUse the names returned by tool discovery when calling tools."
},
{
"id": "tool-catalogs",
"title": "Tool catalogs",
"role": "content",
"text": "When you register an Upstream, the Gateway discovers its tools and stores their definitions in a **catalog**. Refresh the catalog when you add, remove, or change tools at the source.\n\nThe Gateway serves tool discovery requests from this stored catalog. Listing tools does not contact the Upstream or check whether it is available.\n\nYou can disable an Upstream to remove its tools from discovery without deleting its registration.\n\n\n"
},
{
"id": "access-and-credentials",
"title": "Access and credentials",
"role": "content",
"text": "Agents authenticate to a Gateway using an agent key. Deployments configured for identity provider sign-in also support compatible MCP clients signing in through that provider.\n\nAccess is granted at the Gateway level. An agent with permission to use a Gateway can call every tool it exposes, including tools that modify data. Organize Gateways around the access your agents need. Read-only and destructive tool annotations describe tool behavior but do not restrict access.\n\nCredentials for connected sources are configured separately. The Gateway uses those credentials when accessing the sources and does not forward the agent’s key or identity provider token.\n\nSee [Authentication and authorization](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/authentication) for authentication setup and access grants."
},
{
"id": "tool-exposure-modes",
"title": "Tool discovery",
"role": "content",
"text": "A Gateway’s **tool exposure mode** determines how an agent discovers and calls tools."
},
{
"id": "full-mode",
"title": "Full mode",
"role": "content",
"text": "In full mode, the Gateway lists all available tools with their definitions. The agent calls a tool directly using its discovered name, such as `billing__get_invoice`.\n\nFull mode is the default. Use it when the tool definitions fit comfortably in your agent’s context."
},
{
"id": "search-mode",
"title": "Search mode",
"role": "content",
"text": "In search mode, the agent discovers tools as needed. It uses `search_tools` to find tools relevant to a task, reads the returned definitions to choose a tool and its arguments, then calls the selected tool through `run_tool`.\n\nSearch matches query words against tool names, titles, and descriptions. Descriptive tool names and descriptions help agents find the right tools.\n\nUse search mode when you have a large tool set and want to avoid including every definition in the agent’s context. When compression is enabled, the Gateway also exposes tools for working with stored results.\n\nThe application programming interface (API) values for these modes are `FULL` and `SEARCH`.\n\n"
},
{
"id": "tool-policies",
"title": "Working with tool results",
"role": "content",
"text": "Caching and compression address different needs. Caching reuses results across repeated calls. Compression lets an agent work with a large result without receiving it all at once.\n\nBoth features require a Redis database configured for the Gateway and must be enabled in both the deployment and the Gateway configuration. Caching and compression are disabled on Redis Cloud in this release."
},
{
"id": "cache",
"title": "Caching",
"role": "content",
"text": "Caching lets the Gateway reuse a previous tool result for a matching call instead of calling the Upstream again.\n\nCaching is configured for individual tools through a **tool policy**. The policy’s time to live (TTL) determines how long a cached result can be reused. Choose a TTL that reflects how quickly the source data changes and how much staleness your application can tolerate.\n\nFor example, product descriptions may tolerate a longer TTL than inventory availability.\n\n\n\nCache entries are shared by callers with access to the same Gateway. Consider that shared access when deciding which tools to cache. Tool annotations alone do not enable caching.\n\nSee [Manage Gateways and Upstreams](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/manage-gateways) for cache configuration and tool eligibility."
},
{
"id": "compression",
"title": "Compression",
"role": "content",
"text": "Compression reduces the amount of tool-result data sent to the agent by storing eligible large results in Redis. The agent receives a small response containing a **handle**, a reference it can use to work with the stored result.\n\nUsing that handle, the agent can:\n\n- Retrieve a page of records.\n- Select part of the result.\n- Calculate counts and aggregates.\n\nFor example, a product search might return more records than an agent needs to inspect. The agent can count the matches by category, then retrieve a page from the category relevant to the user’s question.\n\nCompression can capture eligible large results automatically when enabled, with tool policies controlling exceptions and handle lifetime. Agents can also explicitly request a stored result with `run_tool_as_handle`.\n\n#### Handle lifetime and access\n\nA handle belongs to the caller that created it. It remains available until its TTL expires or the caller releases it.\n\n#### Result completeness\n\nCapture limits can prevent the Gateway from storing the complete source result. A count or aggregate then describes the captured data, which may represent only part of the source result.\n\nCheck the result’s completeness information and warnings before treating a count or aggregate as a total.\n\nSee the [MCP API Reference](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/api-reference) for handle tools and [Limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/limits) for capture limits and failure behavior."
},
{
"id": "next-steps",
"title": "Next steps",
"role": "content",
"text": "- [Quickstart](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/quickstart): Discover and call your first tools.\n- [Manage Gateways and Upstreams](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/manage-gateways): Connect tool sources and configure Gateway behavior.\n- [Manage Context Surfaces](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/manage-context-surfaces): Generate tools for querying Redis data."
}
],
"examples": []
}