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.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.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.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.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.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.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
3. Batch sparingly - Only batch operations for same partition
4. Limit result sets - Always use LIMIT clause

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