Self-managed Context Gateway API examples

Create the Gateways and the sample Upstream, mint an agent key, verify agent access, and rotate or revoke keys.

Create sample Gateways for full and search mode, register the clinic directory on both, and issue an agent key. The quickstart uses one of these Gateways. The MCP walkthrough uses the search-mode Gateway with compression enabled.

Before you begin, deploy the chart and load the admin token.

Set connection values

Forward the Control Plane and the Identity Service in separate terminals, as in Deploy, then export the connection values:

export IRIS_CONTEXT_GATEWAY_SERVICE_URL='http://localhost:9100'
export IRIS_IDENTITY_URL='http://localhost:9200'
export IRIS_IDENTITY_TOKEN='<identity-service-control-token>'
export IRIS_IDENTITY_TENANT='<tenant-id>'
umask 077

IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN holds the admin token. For application deployment, use the Control Plane and Identity Service endpoints your platform exposes.

Create the Gateways

These examples use Bash, cURL, jq, and redis-cli. Use a dedicated demo Surface database with JSON and Search support. Register it in both planes, separately from the Gateway database. Enable compression.enabled in the Data Plane and use a Gateway database with JSON and maxmemory-policy noeviction.

Choose the registry IDs:

export GATEWAY_DATABASE_ID='<gateway-database-id>'
export SURFACE_DATABASE_ID='<surface-database-id>'

Create a FULL mode Gateway with compression disabled, and a SEARCH mode Gateway with compression enabled:

curl --fail-with-body --silent --show-error \
  -X POST "$IRIS_CONTEXT_GATEWAY_SERVICE_URL/iris/v1/context-gateway/gateways" \
  -H "Authorization: Bearer $IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Front desk", "toolExposureMode": "FULL", "cache": "DISABLED", "compression": "DISABLED"}' > front-desk.json

jq -n --arg database "$GATEWAY_DATABASE_ID" '{
  name: "Operations", toolExposureMode: "SEARCH", databaseId: $database,
  cache: "DISABLED", compression: "ENABLED"
}' > operations-create.json
curl --fail-with-body --silent --show-error \
  -X POST "$IRIS_CONTEXT_GATEWAY_SERVICE_URL/iris/v1/context-gateway/gateways" \
  -H "Authorization: Bearer $IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @operations-create.json > operations.json

export FRONT_DESK_ID="$(jq -er '.gatewayId' front-desk.json)"
export OPERATIONS_ID="$(jq -er '.gatewayId' operations.json)"
jq '{gatewayId, mcpEndpoint, toolExposureMode, compression}' front-desk.json operations.json

The SEARCH mode Gateway explicitly enables compression. Creation fails if its database cannot support it. Cache remains disabled in this walkthrough. Compression also needs compression.enabled on the Data Plane. See Cache and compression.

Register the sample Upstream

Save the complete JSON model from Write a data model as clinic-model.json. It defines Location and Provider, including the specialty and location_id TAG fields. Load these synthetic records into the dedicated demo database. The commands replace only these five sample keys:

export SURFACE_REDIS_URL='<surface-redis-url>'
redis-cli -u "$SURFACE_REDIS_URL" JSON.SET location:clinic-a '$' \
  '{"id":"clinic-a","name":"Clinic A","city":"Boston"}'
redis-cli -u "$SURFACE_REDIS_URL" JSON.SET location:clinic-b '$' \
  '{"id":"clinic-b","name":"Clinic B","city":"Boston"}'
redis-cli -u "$SURFACE_REDIS_URL" JSON.SET provider:p1 '$' \
  '{"id":"p1","specialty":"cardiology","location_id":"clinic-a"}'
redis-cli -u "$SURFACE_REDIS_URL" JSON.SET provider:p2 '$' \
  '{"id":"p2","specialty":"cardiology","location_id":"clinic-a"}'
redis-cli -u "$SURFACE_REDIS_URL" JSON.SET provider:p3 '$' \
  '{"id":"p3","specialty":"cardiology","location_id":"clinic-b"}'

Use the TLS scheme rediss:// when the database requires it. Keep the real connection URL out of source control. For a password, prefer REDISCLI_AUTH over placing the password in command arguments. Importers must normalize line breaks in TEXT fields to spaces before writing records.

Register this model on both Gateways. Sharing the Surface database is intentional here: both Gateways should expose the same demo records.

jq -n --arg database "$SURFACE_DATABASE_ID" --slurpfile model clinic-model.json '{
  name: "Scheduling", namespace: "scheduling", kind: "CONTEXT_SURFACE",
  contextSurface: {databaseId: $database, dataModel: $model[0]}
}' > surface-create.json

for gateway_id in "$FRONT_DESK_ID" "$OPERATIONS_ID"; do
  curl --fail-with-body --silent --show-error \
    -X POST "$IRIS_CONTEXT_GATEWAY_SERVICE_URL/iris/v1/context-gateway/gateways/$gateway_id/upstreams" \
    -H "Authorization: Bearer $IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN" \
    -H 'Content-Type: application/json' \
    --data-binary @surface-create.json > "surface-$gateway_id.json"
  jq -e '(.initialCatalogFailure == null) and (.upstreamId != null)' "surface-$gateway_id.json"
done

If initialCatalogFailure is present, stop and fix the reported database or configuration error before continuing. Indexing happens in the background. Wait for indexing to finish before comparing result counts. The expected dataset has three cardiologists: two at Clinic A and one at Clinic B.

Mint an agent key

Issue one key with a use grant on each Gateway:

jq -n --arg tenant "$IRIS_IDENTITY_TENANT" --arg a "$FRONT_DESK_ID" --arg b "$OPERATIONS_ID" '{
  name: "front-desk-agent",
  grants: [
    {tenant: $tenant, product: "context-gateway", resourceType: "gateway", resourceId: $a, actions: ["use"]},
    {tenant: $tenant, product: "context-gateway", resourceType: "gateway", resourceId: $b, actions: ["use"]}
  ]
}' > agent-grant.json

curl --fail-with-body --silent --show-error \
  -X POST "$IRIS_IDENTITY_URL/v1/api-keys" \
  -H "Authorization: Bearer $IRIS_IDENTITY_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @agent-grant.json > agent-key.json
export IRIS_CONTEXT_GATEWAY_API_KEY="$(jq -er '.token' agent-key.json)"
Warning:

The response's token is the agent key, and it is returned only on creation or rotation. Save it in your secret manager and keep its keyId.

Verify agent access

Use the returned endpoints rather than constructing MCP URLs. They must be reachable from the developer's machine:

export IRIS_CONTEXT_GATEWAY_URL="$(jq -er '.mcpEndpoint' front-desk.json)"
export SEARCH_GATEWAY_URL="$(jq -er '.mcpEndpoint' operations.json)"
python -m venv .venv
source .venv/bin/activate
pip install redis-iris

Use Python 3.11 or later. Run this program to authenticate and list both catalogs:

import os

from redis_iris import ContextGateway

for setting in ("IRIS_CONTEXT_GATEWAY_URL", "SEARCH_GATEWAY_URL"):
    gateway = ContextGateway.from_env({
        "IRIS_CONTEXT_GATEWAY_URL": os.environ[setting],
        "IRIS_CONTEXT_GATEWAY_API_KEY": os.environ["IRIS_CONTEXT_GATEWAY_API_KEY"],
    })
    print(setting, [tool.name for tool in gateway.tools()])

The full-mode catalog includes scheduling__filter_provider. The search-mode catalog includes search_tools, run_tool, and the handle tools, including run_tool_as_handle and count_results. Continue with the quickstart to call the sample tools.

Rotate or revoke agent keys

Rotate a key to issue a new token for the same grants. The grace period keeps the old token valid while applications switch:

curl --fail-with-body --silent --show-error \
  -X POST "$IRIS_IDENTITY_URL/v1/api-keys/<key-id>/rotate?graceSeconds=3600" \
  -H "Authorization: Bearer $IRIS_IDENTITY_TOKEN"

Revoke a key you no longer need:

curl --fail-with-body --silent --show-error \
  -X DELETE "$IRIS_IDENTITY_URL/v1/api-keys/<key-id>" \
  -H "Authorization: Bearer $IRIS_IDENTITY_TOKEN"

A revoked key stops working within the Identity Service cache lifetime, 300 seconds by default.

Hand off to a developer

For the quickstart, give the developer the chosen Gateway’s mcpEndpoint as IRIS_CONTEXT_GATEWAY_URL and the agent key as IRIS_CONTEXT_GATEWAY_API_KEY. Use Operations for search mode or Front desk for full mode. For the MCP walkthrough, provide Operations as IRIS_CONTEXT_GATEWAY_URL. Give platform teams who register Upstreams the Control Plane URL and admin token for Manage Gateways and Upstreams. Remove the local key-response files after you save the token.

Use the CLI instead

The iris context-gateway command-line interface (CLI) in the redis-iris package also manages Gateways. Install the version pinned in the quickstart. With IRIS_IDENTITY_URL and IRIS_IDENTITY_TOKEN exported, create a Gateway, mint its agent key, and write the developer's environment file in one command:

iris context-gateway service create --name front-desk --write-env .env

--write-env writes IRIS_CONTEXT_GATEWAY_URL, IRIS_CONTEXT_GATEWAY_ID, and IRIS_CONTEXT_GATEWAY_API_KEY to the file with mode 0600, and the key is never printed. Add --tool-exposure-mode search and --database-id <gateway-database-id> for the operations Gateway. service key mints an agent key. iris identity keys list --product context-gateway lists keys, and iris identity keys revoke <key-id> revokes one. See Manage Gateways and Upstreams for every operation.

RATE THIS PAGE
Back to top ↑