# MCP API Reference ```json metadata { "schema_version": 2, "title": "MCP API Reference", "description": "Reference for the Redis Context Gateway MCP endpoint, its tools and arguments, its metadata keys, and its errors.", "categories": ["docs","develop","ai"], "tableOfContents": {"sections":[{"id":"endpoint","title":"Endpoint"},{"children":[{"id":"upstream-tools","title":"Upstream tools"},{"id":"search_tools","title":"search_tools"},{"id":"run_tool","title":"run_tool"},{"id":"handle-tools","title":"Handle tools"}],"id":"tools","title":"Tools"},{"id":"metadata-keys","title":"Metadata keys"},{"children":[{"id":"json-rpc-errors","title":"JSON-RPC errors"},{"id":"tool-results-with-an-error-flag","title":"Tool results with an error flag"}],"id":"errors","title":"Errors"}]} , "codeExamples": [] } ``` Agents call Redis Context Gateway through its Model Context Protocol (MCP) endpoint, the Data Plane API. Platform teams manage Gateways and Upstreams through the [Control Plane API Reference](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/control-plane-api-reference). For how to connect, see [MCP](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/mcp). For limits and recovery, see [Limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/limits). ## Endpoint | Item | Value | | --- | --- | | Endpoint | `POST /iris/data/v1/context-gateway/gateways//mcp`, the Gateway's `mcpEndpoint` | | Transport | Streamable HTTP. Responses can be JSON or a server-sent event stream, so send `Accept: application/json, text/event-stream`. | | Credential | An agent key in `Authorization: Bearer ` or `X-Api-Key: `, or an identity provider (IdP) access token in `Authorization: Bearer ` | | Protocol versions | `2026-07-28`, `2025-11-25`, `2025-06-18`, and `2025-03-26` | | Sign-in metadata | `GET /.well-known/oauth-protected-resource/iris/data/v1/context-gateway/gateways//mcp`, served without a credential when the deployment turns on sign-in | Before any MCP message, the endpoint answers `401` without a valid credential, `404` for a Gateway that does not exist or belongs to another tenant, and `403` when the credential has no grant for this Gateway, or the Gateway or its tenant is suspended. It answers `503` when the Gateway's records could not be read. Retry with backoff. ## Tools ### Upstream tools In full mode (`toolExposureMode: FULL`), `tools/list` returns every tool of every enabled Upstream under its qualified name, `__`. Use the returned name unchanged in `tools/call`. The full name is at most 64 characters and contains only letters, digits, underscores, and hyphens. Each definition keeps the Upstream's input schema, output schema, and annotations. The original name remains available in the tool identity metadata. ### `search_tools` Listed in search mode only. | Argument | Type | Description | | --- | --- | --- | | `query` | string | Required. 1 to 200 characters after trimming. `*` matches every tool. | | `limit` | integer | Optional. 1 to 100. Default `5`. | Any other argument is refused with the reason `invalid_arguments`. Search lowercases the query and matches its words against each tool's exposed name and original name first, then its title and description. Ties sort by exposed name, so the order is stable for the same catalog and query. The result, in `structuredContent` and in one text part: | Field | Description | | --- | --- | | `query` | The trimmed query. | | `returned` | The number of definitions in `tools`. | | `matched` | The number of tools that match the query. | | `truncated` | `true` when `returned` is smaller than `matched`. | | `tools` | The matching tool definitions, in ranked order. | ### `run_tool` Listed in search mode only. | Argument | Type | Description | | --- | --- | --- | | `tool` | object | Required. `upstreamId` and `originalName`, copied from a definition's `_meta["com.redis.context-gateway/tool"]`. No other members. | | `toolArgs` | object | Required. The tool's arguments as an object, `{}` when it takes none. | The result is the tool's result. ### Handle tools Listed in both modes when compression is on for the Gateway. | Tool | Arguments | Result | | --- | --- | --- | | `run_tool_as_handle` | full mode: `name` and `toolArgs`. search mode: `tool` and `toolArgs`, as `run_tool` takes them. | A stub for the held result, or a tool error when it cannot be held. It never silently falls back to the whole result. An Upstream's own tool error is returned as that error. | | `page_results` | `handle`, `offset` (default `0`), `limit` | For a collection, items from `offset`, `limit` 1 to 100, default 10. For text, bytes, `limit` up to 16384, default 4096. | | `query_results` | `handle`, `jsonpath`, `offset`, `limit` 1 to 100, default 20 | The matches of a JSONPath expression over the held result, in pages. | | `count_results` | `handle`, optional `jsonpath` and `groupBy` | Counts captured items or selected nodes. With both arguments, selects nodes first, then groups them by the field. | | `aggregate_results` | `handle`, `jsonpath` | `count`, `sum`, `min`, `max`, and `avg` of the selected numbers, and `ignored` for values that are not numbers. | | `describe_result` | `handle` | The held result's description without its preview. | | `release_results` | `handle` | Deletes the held result before its time to live (TTL) ends. | A handle is `h_` followed by 32 hexadecimal digits. A JSONPath expression follows RFC 9535, starts with `$`, is at most 1 kibibyte (KiB), and cannot use the descendant segment `..`. `groupBy` names one field within each item. For example, `state`, `/state`, and `$.state` name the same field, and `user.login` or `/user/login` names a nested field. A grouped response includes `groups`, `distinct`, and `missing`. When the response limit omits groups, check `groupsOmitted` and `groupsWarning` before treating the listed groups as exhaustive. Eligible Context Surface filter and text queries can capture continuation pages. Row, byte, time, and concurrent-capture limits can stop collection early. Semantic and hybrid top-K results are not continued. Check `completeness`, `over`, and `warning` in the handle description and operation results. A count or aggregate describes the captured rows, not records that were never captured. Ordinary automatic capture can return the original inline result when it cannot store a handle. An explicit `run_tool_as_handle` request instead returns a tool error. Release unused handles or narrow the query before requesting another one. Check `completion` first: an explicit capture failure marked `dispatched` means the tool already ran, so retrying a mutating tool can repeat its effect. The `iris` CLI accepts either `--jsonpath` or `--group-by` for its count command, but not both. Use a direct MCP call for combined selection and grouping. ## Metadata keys The Gateway adds these entries to `_meta`. Read them by key, and ignore members you do not know. | Key | Where | Members | | --- | --- | --- | | `com.redis.context-gateway/tool` | Each tool definition | `upstreamId`, `originalName`, and the catalog revision | | `com.redis.context-gateway/invocation` | Each tool result | `schemaVersion` and `traceId`. `tool` and `catalogRevision` only when an Upstream tool was resolved, not for discovery calls or unresolved targets. `cache` (`status` `hit`, `ageMs`) on a cache hit. `upstream` (`serverName`, `serverVersion`) when known. `upstreamDurationMs` when the call reached the Upstream. | | `com.redis.context-gateway/handle` | A handle stub | The handle and its description, without the preview and the next call | | `com.redis.context-gateway/failure` | A tool result with its error flag set | `schemaVersion`, `reason`, `completion`, optional `handleOutcome` for capture failures, and when the failure happened at the Upstream, `stage` and `upstreamCode` | ## Errors A failure reaches the client in one of two ways. ### JSON-RPC errors These failures happen before any call to an Upstream. The JSON-RPC `error.data` holds `schemaVersion`, `reason`, and `traceId`. | Code | `reason` | Cause | | --- | --- | --- | | `-32602` | `unknown_tool` | A direct `tools/call` names a tool the Gateway does not expose. List tools again and use a returned name. | | `-32602` | `invalid_request` | The request is not a valid tool call. | | `-32603` | `gateway_unavailable` | The Gateway could not read its own records. | ### Tool results with an error flag An unknown or inaccessible target passed to `run_tool` or `run_tool_as_handle` returns a tool result with `isError: true`, `reason: unknown_tool`, and `completion: not_dispatched`. Other tool failures also return an error result and the failure entry in `_meta`. In the Python MCP SDK, inspect `result.is_error`. Act on `reason` and `completion`. The text of the result is written for people and can change in any release. For every reason and how to retry, see [Limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/limits).