Cassandra Connector

The Cassandra connector enables AxonFlow agents to execute CQL queries and commands against Apache Cassandra and ScyllaDB clusters with tunable consistency and policy enforcement.

Overview

Property	Value
Type	cassandra
Edition	Community
Auth Methods	Username/Password
Capabilities	query, execute, batch_operations, consistency_levels, token_aware_routing

Use Cases

• High-throughput time-series data queries
• Distributed data access for global applications
• Event sourcing and audit log storage
• Session and user data at scale

Configuration

Environment Variables

# Required - Connection URL
MCP_cassandra_CONNECTION_URL="cassandra://host1:9042,host2:9042/keyspace"

# Authentication
MCP_cassandra_USERNAME="cassandra"
MCP_cassandra_PASSWORD="secure_password"

# Optional - Consistency
MCP_cassandra_CONSISTENCY="QUORUM"  # ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM, LOCAL_ONE

# Optional - Timeouts
MCP_cassandra_TIMEOUT="5s"

# Optional - Connection Pool
MCP_cassandra_NUM_CONNS="2"  # Connections per host

Connection URL Format

cassandra://[host1]:[port],[host2]:[port]/[keyspace]

Examples:

# Single node
cassandra://localhost:9042/mykeyspace

# Multi-node cluster
cassandra://10.0.1.50:9042,10.0.1.51:9042,10.0.1.52:9042/mykeyspace

# ScyllaDB
cassandra://scylla1.example.com:9042,scylla2.example.com:9042/mykeyspace

Connector Config (Customer Portal)

{
  "name": "events-cluster",
  "type": "cassandra",
  "connection_url": "cassandra://node1:9042,node2:9042,node3:9042/events",
  "options": {
    "consistency": "LOCAL_QUORUM",
    "num_conns": 2,
    "timeout": "5s"
  },
  "credentials": {
    "username": "app_user",
    "password": "secure_password"
  }
}

Consistency Levels

Level	Description	Use Case
ONE	Single replica	Low latency reads, eventual consistency
TWO	Two replicas	Balance of consistency and performance
THREE	Three replicas	Higher consistency
QUORUM	Majority of replicas	Strong consistency (default)
ALL	All replicas	Strongest consistency, lowest availability
LOCAL_QUORUM	Majority in local DC	Multi-datacenter deployments
EACH_QUORUM	Majority in each DC	Global consistency
LOCAL_ONE	One replica in local DC	Low latency, local reads

Operations

Query Operations

Execute CQL SELECT queries:

# Basic query
curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "events-cluster",
    "statement": "SELECT event_id, event_type, timestamp FROM events WHERE user_id = ? AND timestamp > ?",
    "parameters": {
      "0": "user-123",
      "1": "2025-12-01T00:00:00Z"
    }
  }'

Response:

{
  "success": true,
  "rows": [
    {
      "event_id": "evt-001",
      "event_type": "login",
      "timestamp": "2025-12-07T10:30:00Z"
    },
    {
      "event_id": "evt-002",
      "event_type": "purchase",
      "timestamp": "2025-12-07T11:45:00Z"
    }
  ],
  "row_count": 2,
  "duration_ms": 3.5,
  "connector": "events-cluster"
}

Query with Consistency Override

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "events-cluster",
    "statement": "SELECT * FROM users WHERE user_id = ?",
    "parameters": {
      "0": "user-123",
      "_consistency": "LOCAL_ONE"
    }
  }'

Execute Operations

Run INSERT, UPDATE, DELETE commands:

# INSERT
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "events-cluster",
    "action": "insert",
    "statement": "INSERT INTO events (event_id, user_id, event_type, timestamp, data) VALUES (?, ?, ?, ?, ?)",
    "parameters": {
      "0": "evt-003",
      "1": "user-123",
      "2": "click",
      "3": "2025-12-08T10:30:00Z",
      "4": "{\"page\": \"/products\"}"
    }
  }'

# UPDATE
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "events-cluster",
    "action": "update",
    "statement": "UPDATE users SET last_login = ? WHERE user_id = ?",
    "parameters": {
      "0": "2025-12-08T10:30:00Z",
      "1": "user-123"
    }
  }'

# DELETE
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "events-cluster",
    "action": "delete",
    "statement": "DELETE FROM sessions WHERE session_id = ?",
    "parameters": {
      "0": "sess-abc123"
    }
  }'

Response:

{
  "success": true,
  "rows_affected": 1,
  "duration_ms": 2.1,
  "message": "insert executed successfully",
  "connector": "events-cluster"
}

CQL Data Types

CQL Type	JSON Type
text, varchar	string
int, bigint	number
float, double, decimal	number
boolean	boolean
timestamp	string (ISO 8601)
uuid, timeuuid	string
blob	base64 string
list, set	array
map	object

Parameterized Queries

CQL uses positional parameters with ? placeholders:

-- Safe parameterized query
SELECT * FROM users WHERE user_id = ? AND status = ?

-- Parameters map by position
{
  "0": "user-123",
  "1": "active"
}

Health Check

curl https://your-axonflow.example.com/mcp/connectors/events-cluster/health

Response:

{
  "healthy": true,
  "latency_ms": 1.8,
  "details": {
    "release_version": "4.1.3",
    "keyspace": "events",
    "consistency": "QUORUM"
  }
}

Best Practices

Data Modeling

1. Design for queries - Cassandra requires knowing your queries upfront
2. Denormalize data - Duplicate data across tables for different access patterns
3. Use partition keys wisely - Distribute data evenly across the cluster
4. Avoid large partitions - Keep partitions under 100MB

Consistency Selection

Scenario	Write	Read
High availability	ONE	ONE
Balanced	QUORUM	QUORUM
Strong consistency	QUORUM	QUORUM
Multi-DC	LOCAL_QUORUM	LOCAL_QUORUM

Performance

1. Use prepared statements - Connector uses them automatically
2. Token-aware routing - Driver routes to correct replica (see Token-Aware Routing)
3. Batch sparingly - Only batch operations for same partition (see Batch Operations)
4. Limit result sets - Always use LIMIT clause

Batch Operations

The connector supports batch operations for executing multiple CQL statements atomically within a single partition. Batches reduce network round trips and provide atomicity guarantees.

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "events-cluster",
    "action": "batch",
    "parameters": {
      "statements": [
        {
          "statement": "INSERT INTO events (user_id, timestamp, event_id, event_type) VALUES (?, ?, ?, ?)",
          "params": ["user-123", "2025-12-08T10:30:00Z", "evt-010", "page_view"]
        },
        {
          "statement": "INSERT INTO events (user_id, timestamp, event_id, event_type) VALUES (?, ?, ?, ?)",
          "params": ["user-123", "2025-12-08T10:30:05Z", "evt-011", "click"]
        },
        {
          "statement": "UPDATE user_stats SET event_count = event_count + 2 WHERE user_id = ?",
          "params": ["user-123"]
        }
      ],
      "batch_type": "LOGGED",
      "_consistency": "LOCAL_QUORUM"
    }
  }'

Batch types:

Type	Description
LOGGED	Default. Provides atomicity across statements (all or nothing). Uses a batch log.
UNLOGGED	No atomicity guarantee. Lower overhead, suitable when all statements target the same partition.
COUNTER	Required for batch counter updates. Cannot mix counter and non-counter operations.

Important: Only batch statements that target the same partition key. Cross-partition batches degrade performance because the coordinator must contact multiple nodes. The connector logs a warning when a batch targets more than one partition.

Token-Aware Routing

The connector uses token-aware routing by default, which routes each query directly to the Cassandra node that owns the data for the query's partition key. This reduces latency by avoiding an extra network hop through a coordinator node.

Token-aware routing is enabled automatically when:

• The connector can discover the cluster's token ring topology
• The query uses a partition key that can be parsed

To verify token-aware routing is active, check the health endpoint:

curl https://your-axonflow.example.com/mcp/connectors/events-cluster/health

The details field will include "token_aware": "enabled" when token-aware routing is active.

When token-aware routing may be disabled:

• If the cluster topology cannot be discovered (e.g., behind a load balancer)
• For queries that do not specify a partition key (e.g., full table scans)
• When num_conns is set to 0 (round-robin only)

Example Schema

-- Events by user (time-series)
CREATE TABLE events_by_user (
    user_id text,
    timestamp timestamp,
    event_id uuid,
    event_type text,
    data text,
    PRIMARY KEY ((user_id), timestamp, event_id)
) WITH CLUSTERING ORDER BY (timestamp DESC);

-- Create user for AxonFlow
CREATE ROLE axonflow WITH PASSWORD = 'secure_password' AND LOGIN = true;
GRANT SELECT, INSERT, UPDATE, DELETE ON KEYSPACE events TO axonflow;

Troubleshooting

Connection Timeout

• Verify cluster hosts are reachable
• Check port 9042 is open
• Ensure cluster is healthy: nodetool status

Authentication Failed

• Verify username and password
• Check role has LOGIN privilege
• Ensure authenticator is configured in cassandra.yaml

NoHostAvailable

• At least one node must be reachable
• Check network connectivity to all hosts
• Verify port 9042 is accessible

Read/Write Timeout

• Reduce consistency level
• Check cluster health
• Verify data isn't in large partitions
• Increase timeout in configuration

Invalid Keyspace

• Verify keyspace exists: DESCRIBE KEYSPACES;
• Check role has access to keyspace
• Ensure keyspace name is correct in URL

ScyllaDB Compatibility

The connector works with ScyllaDB (Cassandra-compatible):

{
  "name": "scylla-cluster",
  "type": "cassandra",
  "connection_url": "cassandra://scylla1:9042,scylla2:9042/mykeyspace"
}

ScyllaDB-specific considerations:

• Generally faster performance
• Same CQL syntax
• Compatible drivers
• May support lower consistency levels for same guarantees

Related

• PostgreSQL Connector
• MongoDB Connector
• Redis Connector
• MCP Overview