Back to Documentation

Stateful Operations

Persistent state management for multi-step workflows. Give agents memory across tool calls.

State Management Tools

state.put

Store key-value pairs with optional TTL

{
  "tool": "state.put",
  "arguments": {
    "key": "workflow_id",
    "value": "wf_123456",
    "ttl": 3600,
    "scope": "session"
  }
}

state.get

Retrieve stored values by key

{
  "tool": "state.get",
  "arguments": {
    "key": "workflow_id",
    "scope": "session"
  }
}

state.list

List all keys in a scope

{
  "tool": "state.list",
  "arguments": {
    "scope": "session",
    "pattern": "ticket_*"
  }
}

state.clear

Delete keys or clear entire scope

{
  "tool": "state.clear",
  "arguments": {
    "keys": ["temp_*"],
    "scope": "session"
  }
}

State Scopes

Session Scope

Persists for the duration of a conversation or workflow

  • • TTL: 1-6 hours (configurable)
  • • Use case: Working memory, temporary IDs
  • • Isolation: Per conversation/thread

User Scope

Persists across sessions for a specific user

  • • TTL: 7-30 days (configurable)
  • • Use case: User preferences, history
  • • Isolation: Per authenticated user

Global Scope

Shared across all sessions and users

  • • TTL: Configurable or permanent
  • • Use case: Shared resources, lookups
  • • Isolation: Per tenant/organization

Workflow Example

Multi-Step Order Processing

Step 1: Create Order

// Create order and store ID
const order = await api.createOrder({...});
await state.put("order_id", order.id, {scope: "session"});
await state.put("order_status", "created", {scope: "session"});

Step 2: Add Items

// Retrieve order ID
const orderId = await state.get("order_id");
await api.addItems(orderId, items);
await state.put("item_count", items.length, {scope: "session"});

Step 3: Process Payment

// Use stored order data
const orderId = await state.get("order_id");
const payment = await api.processPayment(orderId);
await state.put("payment_id", payment.id, {scope: "session"});
await state.put("order_status", "paid", {scope: "session"});

Step 4: Cleanup

// Clear temporary state
await state.clear({
  keys: ["order_*", "item_*", "payment_*"],
  scope: "session"
});

Security & Isolation

State Isolation Guarantees

  • ✓Session state is isolated per conversation thread
  • ✓User state requires authentication and is per-user
  • ✓Tenant isolation prevents cross-organization access
  • ✓Encryption at rest and in transit
  • ✓Automatic expiration of temporary state

Configuration

{
  "state": {
    "enabled": true,
    "storage": {
      "backend": "redis",
      "connection": "redis://localhost:6379",
      "key_prefix": "mcpify:state:"
    },
    "scopes": {
      "session": {
        "ttl": 3600,
        "max_keys": 1000,
        "max_value_size": "1MB"
      },
      "user": {
        "ttl": 604800,
        "max_keys": 100,
        "max_value_size": "100KB"
      },
      "global": {
        "ttl": null,
        "max_keys": 10000,
        "max_value_size": "10KB",
        "require_admin": true
      }
    },
    "cleanup": {
      "interval": 300,
      "batch_size": 1000
    }
  }
}

Give agents perfect memory

Stateful operations ensure nothing gets lost between tool calls.

Get StartedArchitecture Guide