redis-context-gateway

Python SDK for Redis Context Gateway. The REST client is generated by Speakeasy from the Gateway control-plane API, the same way as the other Iris SDKs. A small helper connects agents to a Gateway's MCP endpoint with the official mcp library.

Unpublished first increment, generated from redislabsdev/iris@7b8fb322e. Python 3.10 or later.

Control plane

from redis_context_gateway import ContextGatewayClient

with ContextGatewayClient(server_url=control_plane_url, admin_token=admin_token) as client:
    gateway = client.gateways.create(display_name="Docs", tool_exposure_mode="search")
    upstream = client.upstreams.create(
        gateway_id=gateway.id,
        display_name="Docs MCP",
        namespace="docs",
        connection={"endpoint": upstream_mcp_url},
        authentication={"methods": [{"bearer": {"value": upstream_token}}]},
    )

Every product call sends the admin token. The health probes (client.health.live(), client.health.ready()) send no credential. Async variants end in _async. See USAGE.md and docs/ for every operation and model.

Agents (MCP)

from redis_context_gateway.mcp import connect

async with connect(gateway.mcp_endpoint, agent_key) as session:
    found = await session.call_tool("search_tools", {"query": "find an issue"})
    result = await session.call_tool(
        "run_tool", {"tool": {"upstreamId": upstream.id, "originalName": "get_issue"}, "toolArgs": {"id": 42}}
    )

connect returns an initialized official mcp.ClientSession, so Lens instrumentation applies as is. The agent key is an Identity Service key with a context-retriever / cr-gateway / use grant for the Gateway. Search tools, run_tool and the result handle tools are ordinary tool calls. A tool failure comes back as a result with isError: true, not an exception.

MCP reads default to a 300-second inactivity timeout, with 30-second connect, write and connection-pool budgets. Pass timeout=10 to use ten seconds for every HTTP timeout, or timeout=httpx.Timeout(30, read=600) for a separate read budget. These are HTTP inactivity limits, not a total tool-call deadline. REST timeout defaults are unchanged.

Safety

• Neither client follows redirects, so the admin token and agent keys stay on the Gateway.
• Plain HTTP is refused unless the host is loopback (localhost, 127.0.0.0/8 or ::1).
• Each request must match its own operation's method, path and query names, so an ID like ../../v1/gateways fails before anything is sent. A custom HTTP client that can't turn redirects off is refused with a TypeError.
• The SDK never reads credentials from environment variables. Pass them in explicitly. The redis-iris CLI and goal objects own IRIS_CONTEXT_GATEWAY_* settings and the [context_gateway] config table.
• Upstream secrets are write-only: no response model carries them.
• Generated payload debugging is disabled, even when debug_logger is supplied, because it would log request secrets. Application logging and custom HTTP transports are outside this guarantee. Do not log whole generated exceptions: validation diagnostics can retain supplied credentials, and response errors retain server-provided bodies.
• No call is retried automatically.

Development

uv venv && uv pip install -e . pytest pytest-asyncio ruff
# Python 3.11+: install the local Lens package for its integration test.
uv pip install ../lens-python-sdk
.venv/bin/python -m pytest tests

Hand-written files are src/redis_context_gateway/_hooks/registration.py, src/redis_context_gateway/mcp.py, tests/ and this README, protected by .genignore. Everything else is regenerated by node scripts/generate-context-gateway.mjs from the repository root.