MongoDB Connector

The MongoDB connector enables AxonFlow agents to perform CRUD operations, aggregations, and complex queries against MongoDB databases with full connection pooling and policy enforcement.

Overview

Property	Value
Type	mongodb
Edition	Community
Auth Methods	Connection URI, Username/Password, X.509
Capabilities	query, execute, aggregation, connection_pooling, transactions, change_streams

Use Cases

• Document retrieval for RAG pipelines
• Store agent-generated content and embeddings
• Access NoSQL data stores in agent workflows
• Real-time data access with change streams

Configuration

Environment Variables

# Option 1: Full MongoDB URI
MCP_mongodb_CONNECTION_URL="mongodb://user:pass@host1:27017,host2:27017/database?replicaSet=rs0"

# Option 2: Build from components
MCP_mongodb_HOST="localhost"
MCP_mongodb_PORT="27017"
MCP_mongodb_DATABASE="mydb"
MCP_mongodb_USER="myuser"
MCP_mongodb_PASSWORD="mypassword"

# Optional - Replica Set
MCP_mongodb_HOSTS="host1:27017,host2:27017,host3:27017"
MCP_mongodb_REPLICA_SET="rs0"

# Optional - Connection Pool
MCP_mongodb_MAX_POOL_SIZE="100"
MCP_mongodb_MIN_POOL_SIZE="10"
MCP_mongodb_CONNECT_TIMEOUT="10s"
MCP_mongodb_SOCKET_TIMEOUT="30s"

# Optional - Read Preference
MCP_mongodb_READ_PREFERENCE="primaryPreferred"  # primary, secondary, nearest

# Optional - TLS
MCP_mongodb_TLS="true"
MCP_mongodb_TLS_INSECURE="false"

# Optional - Auth Database
MCP_mongodb_AUTH_DATABASE="admin"

Connection URI Format

mongodb://[user]:[password]@[host1]:[port1],[host2]:[port2]/[database]?[options]

Common Options:

• replicaSet=rs0 - Replica set name
• authSource=admin - Authentication database
• tls=true - Enable TLS
• retryWrites=true - Retry write operations
• w=majority - Write concern

Connector Config (Customer Portal)

{
  "name": "app-mongodb",
  "type": "mongodb",
  "options": {
    "host": "mongodb.example.com",
    "port": 27017,
    "database": "appdb",
    "collection": "documents",
    "max_pool_size": 100,
    "min_pool_size": 10,
    "read_preference": "primaryPreferred"
  },
  "credentials": {
    "username": "app_user",
    "password": "secure_password"
  }
}

Operations

Query Operations

The MongoDB connector supports multiple query types via the statement field:

Find Documents

# Basic find
curl -X POST https://your-axonflow.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "app-mongodb",
    "statement": "find:users",
    "parameters": {
      "status": "active",
      "age": {"$gte": 18}
    }
  }'

# With projection, sort, and limit
curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-mongodb",
    "statement": "find:users",
    "parameters": {
      "filter": {"status": "active"},
      "projection": {"name": 1, "email": 1, "_id": 0},
      "sort": {"createdAt": -1},
      "limit": 10,
      "skip": 0
    }
  }'

Response:

{
  "success": true,
  "rows": [
    {"name": "Alice", "email": "[email protected]"},
    {"name": "Bob", "email": "[email protected]"}
  ],
  "row_count": 2,
  "duration_ms": 5.2,
  "connector": "app-mongodb"
}

Find One Document

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-mongodb",
    "statement": "findone:users",
    "parameters": {
      "_id": {"$oid": "507f1f77bcf86cd799439011"}
    }
  }'

Aggregation Pipeline

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-mongodb",
    "statement": "aggregate:orders",
    "parameters": {
      "pipeline": [
        {"$match": {"status": "completed"}},
        {"$group": {
          "_id": "$customerId",
          "totalSpent": {"$sum": "$amount"},
          "orderCount": {"$sum": 1}
        }},
        {"$sort": {"totalSpent": -1}},
        {"$limit": 10}
      ],
      "allowDiskUse": true
    }
  }'

Count Documents

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-mongodb",
    "statement": "count:users",
    "parameters": {
      "status": "active"
    }
  }'

Response:

{
  "rows": [{"count": 1234}],
  "row_count": 1
}

Distinct Values

curl -X POST https://your-axonflow.com/mcp/resources/query \
  -d '{
    "connector": "app-mongodb",
    "statement": "distinct:products",
    "parameters": {
      "field": "category",
      "filter": {"inStock": true}
    }
  }'

Execute Operations

Insert One

curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-mongodb",
    "action": "insertOne",
    "statement": "users",
    "parameters": {
      "document": {
        "name": "Charlie",
        "email": "[email protected]",
        "createdAt": {"$date": "2025-12-08T10:30:00Z"}
      }
    }
  }'

Response:

{
  "success": true,
  "rows_affected": 1,
  "message": "Inserted 1 document (id=507f1f77bcf86cd799439011)"
}

Insert Many

curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-mongodb",
    "action": "insertMany",
    "statement": "users",
    "parameters": {
      "documents": [
        {"name": "User1", "email": "[email protected]"},
        {"name": "User2", "email": "[email protected]"}
      ],
      "ordered": true
    }
  }'

Update One

curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-mongodb",
    "action": "updateOne",
    "statement": "users",
    "parameters": {
      "filter": {"email": "[email protected]"},
      "update": {"$set": {"status": "verified", "verifiedAt": {"$date": "2025-12-08T10:30:00Z"}}},
      "upsert": false
    }
  }'

Update Many

curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-mongodb",
    "action": "updateMany",
    "statement": "users",
    "parameters": {
      "filter": {"lastLogin": {"$lt": {"$date": "2025-01-01T00:00:00Z"}}},
      "update": {"$set": {"status": "inactive"}}
    }
  }'

Delete One / Delete Many

# Delete one
curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-mongodb",
    "action": "deleteOne",
    "statement": "users",
    "parameters": {
      "_id": {"$oid": "507f1f77bcf86cd799439011"}
    }
  }'

# Delete many
curl -X POST https://your-axonflow.com/mcp/tools/execute \
  -d '{
    "connector": "app-mongodb",
    "action": "deleteMany",
    "statement": "sessions",
    "parameters": {
      "expiresAt": {"$lt": {"$date": "2025-12-01T00:00:00Z"}}
    }
  }'

Statement Format

The statement field uses the format: operation:collection

Operation	Description
find:collection	Find multiple documents
findone:collection	Find single document
aggregate:collection	Run aggregation pipeline
count:collection	Count matching documents
distinct:collection	Get distinct field values

For execute operations, the action determines the operation type.

Special Types

MongoDB-specific types in parameters:

{
  "_id": {"$oid": "507f1f77bcf86cd799439011"},
  "createdAt": {"$date": "2025-12-08T10:30:00Z"},
  "age": {"$gt": 18},
  "tags": {"$in": ["mongodb", "database"]}
}

Connection Pooling

Setting	Default	Description
max_pool_size	100	Maximum connections in pool
min_pool_size	10	Minimum connections maintained
connect_timeout	10s	Connection timeout
socket_timeout	30s	Socket operation timeout
server_selection_timeout	30s	Time to select server

Health Check

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

Response:

{
  "healthy": true,
  "latency_ms": 2.3,
  "details": {
    "database": "appdb",
    "mongodb_version": "7.0.4",
    "current_connections": "25",
    "available_connections": "75"
  }
}

Best Practices

Security

1. Use authentication - Never run MongoDB without auth in production
2. Enable TLS - Encrypt connections with tls=true
3. Network isolation - Place MongoDB in private subnet
4. Role-based access - Create users with minimal permissions

Performance

1. Create indexes - Index fields used in queries and sorts
2. Use projections - Only fetch needed fields
3. Limit results - Always use limit for large collections
4. Read preferences - Use secondaryPreferred for read-heavy workloads

Example User Setup

// Create read-only user
db.createUser({
  user: "axonflow_reader",
  pwd: "secure_password",
  roles: [
    { role: "read", db: "appdb" }
  ]
});

// Create read-write user
db.createUser({
  user: "axonflow_writer",
  pwd: "secure_password",
  roles: [
    { role: "readWrite", db: "appdb" }
  ]
});

Troubleshooting

Connection Timeout

• Verify host and port are correct
• Check firewall/security group allows connection
• Ensure MongoDB is running and accepting connections

Authentication Failed

• Verify username and password
• Check authSource matches authentication database (usually admin)
• Ensure user has required roles

Replica Set Issues

• Verify all replica set members are accessible
• Check replica set name matches configuration
• Ensure primary is elected and accessible

Slow Queries

• Use .explain() to analyze query plan
• Add indexes for frequently queried fields
• Check for collection scans in slow query log

Related

• PostgreSQL Connector
• Redis Connector
• MCP Overview