Redis Connector

The Redis connector enables AxonFlow agents to interact with Redis for caching, key-value storage, and real-time data access with full connection pooling and policy enforcement.

Overview

Property	Value
Type	redis
Edition	Community
Auth Methods	Password, ACL Username/Password
Capabilities	query, execute, cache, kv-store

Use Cases

• Cache LLM responses for repeated queries
• Store session data and conversation context
• Rate limiting and quota management
• Real-time feature flags and configuration

Configuration

Environment Variables

# Required
MCP_redis_HOST="localhost"
MCP_redis_PORT="6379"

# Optional - Authentication
MCP_redis_PASSWORD="secure_password"
MCP_redis_USERNAME="default"  # For Redis 6+ ACL

# Optional - Database
MCP_redis_DB="0"  # Redis database number (0-15)

# Optional - Connection Pool
MCP_redis_POOL_SIZE="100"
MCP_redis_MIN_IDLE_CONNS="10"
MCP_redis_DIAL_TIMEOUT="5s"
MCP_redis_READ_TIMEOUT="3s"
MCP_redis_WRITE_TIMEOUT="3s"

# Optional - TLS
MCP_redis_TLS="true"
MCP_redis_TLS_INSECURE="false"

Connector Config (Customer Portal)

{
  "name": "app-cache",
  "type": "redis",
  "options": {
    "host": "redis.example.com",
    "port": 6379,
    "db": 0,
    "pool_size": 100,
    "min_idle_conns": 10
  },
  "credentials": {
    "password": "secure_password"
  }
}

Operations

Query Operations

GET - Retrieve a Value

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "app-cache",
    "statement": "GET",
    "parameters": {
      "key": "user:123:profile"
    }
  }'

Response:

{
  "success": true,
  "rows": [
    {
      "key": "user:123:profile",
      "exists": true,
      "value": "{\"name\":\"Alice\",\"email\":\"[email protected]\"}",
      "ttl": 3600
    }
  ],
  "row_count": 1,
  "duration_ms": 0.5
}

EXISTS - Check Key Existence

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-cache",
    "statement": "EXISTS",
    "parameters": {
      "key": "session:abc123"
    }
  }'

Response:

{
  "rows": [{"key": "session:abc123", "exists": true}]
}

TTL - Get Time to Live

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-cache",
    "statement": "TTL",
    "parameters": {
      "key": "user:123:profile"
    }
  }'

Response:

{
  "rows": [{"key": "user:123:profile", "ttl": 3542}]
}

KEYS - List Keys by Pattern

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-cache",
    "statement": "KEYS",
    "parameters": {
      "pattern": "user:*:profile",
      "limit": 100
    }
  }'

Response:

{
  "rows": [
    {"key": "user:123:profile"},
    {"key": "user:456:profile"},
    {"key": "user:789:profile"}
  ],
  "row_count": 3
}

STATS - Get Cache Statistics

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-cache",
    "statement": "STATS"
  }'

Response:

{
  "rows": [{
    "db_size": 15234,
    "pool_hits": 892341,
    "pool_misses": 1234,
    "pool_timeouts": 0,
    "pool_total_conn": 100,
    "pool_idle_conn": 95
  }]
}

Execute Operations

SET - Store a Value

curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-cache",
    "action": "SET",
    "parameters": {
      "key": "user:123:profile",
      "value": {"name": "Alice", "email": "[email protected]"},
      "ttl": 3600
    }
  }'

TTL Options:

• Integer: seconds (e.g., 3600 for 1 hour)
• String duration: "1h", "30m", "24h"
• Omit for no expiration

Response:

{
  "success": true,
  "rows_affected": 1,
  "message": "SET user:123:profile (ttl=1h0m0s)"
}

DELETE - Remove a Key

curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-cache",
    "action": "DELETE",
    "parameters": {
      "key": "user:123:profile"
    }
  }'

Response:

{
  "success": true,
  "rows_affected": 1,
  "message": "DELETE user:123:profile"
}

EXPIRE - Set TTL on Existing Key

curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-cache",
    "action": "EXPIRE",
    "parameters": {
      "key": "session:abc123",
      "ttl": 1800
    }
  }'

Value Serialization

The connector automatically handles value serialization:

Input Type	Storage	Retrieval
String	As-is	String
Object/Array	JSON string	JSON string (parse client-side)
Number	String	String
Binary	Not supported	N/A

Example: Storing JSON

{
  "key": "config:feature-flags",
  "value": {
    "dark_mode": true,
    "beta_features": ["map", "export"],
    "max_retries": 3
  }
}

Connection Pooling

Setting	Default	Description
pool_size	100	Maximum connections in pool
min_idle_conns	10	Minimum idle connections
dial_timeout	5s	Connection timeout
read_timeout	3s	Read operation timeout
write_timeout	3s	Write operation timeout

Health Check

curl https://your-axonflow.com/mcp/connectors/app-cache/health

Response:

{
  "healthy": true,
  "latency_ms": 0.3,
  "details": {
    "db_size": "15234",
    "connected": "true",
    "pool_stats": "{Hits:892341 Misses:1234 Timeouts:0 TotalConns:100 IdleConns:95 StaleConns:0}"
  }
}

Best Practices

Key Naming Conventions

Use a consistent naming pattern for keys:

<entity>:<id>:<attribute>

Examples:

• user:123:profile - User profile data
• session:abc123 - Session data
• cache:llm:hash123 - LLM response cache
• rate:api:user:123 - Rate limiting counter
• config:feature:dark_mode - Feature flag

TTL Strategy

Use Case	Recommended TTL
LLM response cache	1-24 hours
Session data	30 minutes - 24 hours
Rate limiting	1-60 minutes
Feature flags	5-15 minutes
User profiles	1-6 hours

Security

1. Use authentication - Always set a password in production
2. Network isolation - Place Redis in private subnet
3. TLS encryption - Enable for sensitive data
4. ACLs - Use Redis 6+ ACLs for fine-grained access

Performance

1. Use pipelining - Batch multiple operations
2. Appropriate TTLs - Don't cache forever
3. Key patterns - Use efficient patterns for SCAN operations
4. Connection pooling - Configure based on workload

Example: LLM Response Caching

# Generate cache key from prompt hash
CACHE_KEY="cache:llm:$(echo -n "$PROMPT" | sha256sum | cut -c1-16)"

# Check cache
CACHED=$(curl -s -X POST .../query -d "{\"statement\":\"GET\",\"parameters\":{\"key\":\"$CACHE_KEY\"}}")

if [ "$(echo $CACHED | jq '.rows[0].exists')" = "true" ]; then
  echo "Cache hit!"
  echo $CACHED | jq '.rows[0].value'
else
  # Call LLM and cache response
  RESPONSE=$(call_llm "$PROMPT")
  curl -X POST .../execute -d "{
    \"action\":\"SET\",
    \"parameters\":{
      \"key\":\"$CACHE_KEY\",
      \"value\":$RESPONSE,
      \"ttl\":3600
    }
  }"
fi

Troubleshooting

Connection Refused

• Verify Redis is running on specified host/port
• Check firewall allows connection
• Ensure bind directive in redis.conf allows external connections

Authentication Error

• Verify password is correct
• For Redis 6+ with ACLs, ensure username is correct
• Check requirepass in redis.conf

Connection Pool Exhausted

• Increase pool_size
• Check for connection leaks
• Monitor with STATS query

Timeout Errors

• Check network latency to Redis
• Increase timeout values if needed
• Consider Redis Cluster for high throughput

Related

• PostgreSQL Connector
• MongoDB Connector
• MCP Overview