ZeroDB MCP Server v2.2.0
Enterprise-grade Model Context Protocol (MCP) server providing full access to ZeroDB's vector search, quantum compression, PostgreSQL, NoSQL operations, and persistent memory for AI agents.
🆕 What's New in v2.2.0
- 3 New Embedding Tools - Free embedding generation with
zerodb_generate_embeddings,zerodb_embed_and_store,zerodb_semantic_search - Multi-Dimension Support - Use 384, 768, 1024, or 1536 dimension vectors
- Free Models - BAAI/bge-small/base/large-en-v1.5 (no API costs!)
- 151 Tests Passing - 80.76% coverage with comprehensive TDD test suite
- See EMBEDDING_TOOLS_GUIDE.md for complete documentation
Key Features
- 69 Complete Operations - Full API coverage across all ZeroDB capabilities + new embedding tools
- Vector Search - Semantic similarity search with 384/768/1024/1536-dimensional embeddings
- Free Embeddings - Generate embeddings with BAAI BGE models (no OpenAI costs!)
- Quantum Compression - Advanced vector compression using quantum algorithms
- PostgreSQL Operations - Full SQL query execution, schema management, backups, and statistics
- NoSQL Tables - Flexible table operations for structured data
- File Storage - Secure file upload, download, and management
- Event System - Event-driven architecture with pub/sub support
- Project Management - Multi-tenant project isolation and management
- RLHF Integration - Reinforcement Learning from Human Feedback collection
- Admin Tools - System monitoring, optimization, and health checks
- Enterprise Security - JWT authentication with automatic token renewal + SQL injection prevention
- 90%+ Test Coverage - Comprehensive test suite for production reliability
Table of Contents
- Installation
- Quick Start
- API Reference
- Configuration
- Examples
- Migration Guide
- Troubleshooting
- Contributing
- License
Installation
NPM Global Installation
npm install -g ainative-zerodb-mcp-server
NPX (No Installation Required)
npx ainative-zerodb-mcp-server
Requirements
- Node.js >= 18.0.0
- NPM >= 9.0.0
- ZeroDB account with API credentials (see below)
Getting Started
Step 1: Create Your ZeroDB Account
Before using the MCP server, you need a ZeroDB account and project.
Option A: Register via Web (Recommended)
Visit: https://api.ainative.studio/docs
- Click on "Register User" endpoint
- Use the "Try it out" feature
- Enter your email, password, and username
Option B: Register via API
curl -X POST 'https://api.ainative.studio/v1/public/auth/register' \
-H 'Content-Type: application/json' \
-d '{
"email": "your-email@example.com",
"password": "YourSecurePassword123!",
"username": "yourname"
}'
Response:
{
"email": "your-email@example.com",
"id": "user-uuid-here",
"username": "yourname"
}
Step 2: Create a Project
After registration, create a project to get your PROJECT_ID:
# 1. Login to get your access token
curl -X POST 'https://api.ainative.studio/v1/public/auth/login-json' \
-H 'Content-Type: application/json' \
-d '{
"username": "your-email@example.com",
"password": "YourSecurePassword123!"
}'
Response:
{
"access_token": "eyJhbGc...",
"token_type": "bearer",
"expires_in": 1800
}
# 2. Create a project using your token
curl -X POST 'https://api.ainative.studio/v1/public/projects' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
-H 'Content-Type: application/json' \
-d '{
"name": "My ZeroDB MCP Project",
"description": "Project for Claude Desktop MCP integration"
}'
Response:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My ZeroDB MCP Project",
"status": "ACTIVE",
...
}
Save this Project ID! You'll need it for the MCP configuration.
Quick Start
Step 3: Configure Claude Desktop
Add to your Claude Desktop configuration file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"zerodb": {
"command": "npx",
"args": ["ainative-zerodb-mcp-server"],
"env": {
"ZERODB_API_URL": "https://api.ainative.studio",
"ZERODB_PROJECT_ID": "your-project-id-here",
"ZERODB_USERNAME": "your-email@example.com",
"ZERODB_PASSWORD": "your-password",
"MCP_CONTEXT_WINDOW": "8192",
"MCP_RETENTION_DAYS": "30"
}
}
}
}
Step 4: Restart Claude Desktop
After saving the configuration, restart Claude Desktop to activate the MCP server.
Step 5: Test Your First Operation
In Claude Desktop, try:
Store a memory: "This is my first ZeroDB memory entry"
Claude will use the zerodb_store_memory tool to persist this information.
API Reference
All 60 operations are organized into 9 categories. Each operation is exposed as an MCP tool that Claude can invoke.
Memory Operations
1. zerodb_store_memory
Store agent memory in ZeroDB for persistent context across sessions.
Parameters:
content(string, required) - Memory content to storerole(string, required) - Message role:"user","assistant", or"system"session_id(string, optional) - Session identifier (auto-generated if not provided)agent_id(string, optional) - Agent identifier (auto-generated if not provided)metadata(object, optional) - Additional metadata
Returns:
{
"memory_id": "uuid",
"created_at": "2025-10-14T12:00:00Z"
}
Example:
{
"content": "User prefers dark mode and TypeScript",
"role": "system",
"metadata": {
"category": "preferences"
}
}
2. zerodb_search_memory
Search agent memory using semantic similarity.
Parameters:
query(string, required) - Search querysession_id(string, optional) - Filter by sessionagent_id(string, optional) - Filter by agentrole(string, optional) - Filter by rolelimit(number, optional) - Max results (default: 10)
Returns:
{
"memories": [
{
"memory_id": "uuid",
"content": "string",
"role": "user|assistant|system",
"created_at": "timestamp",
"similarity_score": 0.95
}
]
}
Example:
{
"query": "What were the user's preferences?",
"limit": 5
}
3. zerodb_get_context
Get agent context window for current session, optimized for token limits.
Parameters:
session_id(string, required) - Session identifieragent_id(string, optional) - Agent identifiermax_tokens(number, optional) - Max tokens in context (default: 8192)
Returns:
{
"session_id": "uuid",
"agent_id": "uuid",
"total_tokens": 1024,
"memory_count": 15,
"messages": [
{
"role": "user",
"content": "string",
"timestamp": "2025-10-14T12:00:00Z"
}
]
}
Example:
{
"session_id": "session-123",
"max_tokens": 4096
}
Vector Operations
4. zerodb_store_vector
Store vector embedding with metadata (exactly 1536 dimensions).
Parameters:
vector_embedding(array[number], required) - 1536-dimensional vectordocument(string, required) - Source document textmetadata(object, optional) - Document metadatanamespace(string, optional) - Vector namespace (default: "windsurf")
Returns:
{
"vector_id": "uuid",
"namespace": "windsurf"
}
Example:
{
"vector_embedding": [0.1, 0.2, ..., 0.9], // 1536 values
"document": "This is the source text",
"metadata": {
"source": "documentation",
"page": 42
}
}
5. zerodb_batch_upsert_vectors
Batch upsert multiple vectors for improved performance.
Parameters:
vectors(array, required) - Array of vector objectsvector_embedding(array[number], required) - 1536-dimensional vectordocument(string, required) - Source documentmetadata(object, optional) - Document metadata
namespace(string, optional) - Vector namespace
Returns:
{
"success_count": 100,
"failed_count": 0,
"vector_ids": ["uuid1", "uuid2", ...]
}
Example:
{
"vectors": [
{
"vector_embedding": [...],
"document": "Document 1",
"metadata": {"index": 1}
},
{
"vector_embedding": [...],
"document": "Document 2",
"metadata": {"index": 2}
}
],
"namespace": "knowledge-base"
}
6. zerodb_search_vectors
Search vectors using semantic similarity.
Parameters:
query_vector(array[number], required) - 1536-dimensional query vectornamespace(string, optional) - Vector namespacelimit(number, optional) - Max results (default: 10)threshold(number, optional) - Similarity threshold 0-1 (default: 0.7)
Returns:
{
"vectors": [
{
"vector_id": "uuid",
"document": "string",
"similarity_score": 0.95,
"metadata": {}
}
]
}
Example:
{
"query_vector": [...], // 1536 values
"namespace": "windsurf",
"limit": 20,
"threshold": 0.8
}
7. zerodb_delete_vector
Delete a specific vector by ID.
Parameters:
vector_id(string, required) - Vector UUID to delete
Returns:
{
"success": true,
"deleted_id": "uuid"
}
Example:
{
"vector_id": "123e4567-e89b-12d3-a456-426614174000"
}
8. zerodb_get_vector
Retrieve a specific vector by ID.
Parameters:
vector_id(string, required) - Vector UUID to retrieve
Returns:
{
"vector_id": "uuid",
"vector_embedding": [...],
"document": "string",
"metadata": {},
"created_at": "timestamp"
}
Example:
{
"vector_id": "123e4567-e89b-12d3-a456-426614174000"
}
9. zerodb_list_vectors
List vectors with pagination and filtering.
Parameters:
namespace(string, optional) - Filter by namespacelimit(number, optional) - Results per page (default: 50)offset(number, optional) - Pagination offset (default: 0)
Returns:
{
"vectors": [...],
"total_count": 1000,
"limit": 50,
"offset": 0
}
Example:
{
"namespace": "windsurf",
"limit": 100,
"offset": 200
}
10. zerodb_vector_stats
Get statistics about vector storage.
Parameters:
namespace(string, optional) - Filter by namespace
Returns:
{
"total_vectors": 10000,
"namespaces": {
"windsurf": 5000,
"default": 5000
},
"storage_bytes": 1048576,
"avg_dimension": 1536
}
Example:
{
"namespace": "windsurf"
}
11. zerodb_create_vector_index
Create a vector search index for improved performance.
Parameters:
namespace(string, required) - Namespace to indexindex_type(string, optional) - Index type: "ivfflat" or "hnsw" (default: "hnsw")params(object, optional) - Index-specific parameters
Returns:
{
"index_id": "uuid",
"namespace": "windsurf",
"index_type": "hnsw",
"status": "created"
}
Example:
{
"namespace": "windsurf",
"index_type": "hnsw",
"params": {
"m": 16,
"ef_construction": 200
}
}
12. zerodb_optimize_vectors
Optimize vector storage and indexes.
Parameters:
namespace(string, optional) - Namespace to optimize
Returns:
{
"optimized": true,
"space_saved_bytes": 102400,
"duration_ms": 1500
}
Example:
{
"namespace": "windsurf"
}
13. zerodb_export_vectors
Export vectors to external format.
Parameters:
namespace(string, required) - Namespace to exportformat(string, optional) - Export format: "json" or "csv" (default: "json")include_embeddings(boolean, optional) - Include vector data (default: false)
Returns:
{
"export_id": "uuid",
"download_url": "https://...",
"expires_at": "timestamp"
}
Example:
{
"namespace": "windsurf",
"format": "json",
"include_embeddings": true
}
Quantum Operations
14. zerodb_quantum_compress
Compress vector using quantum algorithms for reduced storage.
Parameters:
vector_embedding(array[number], required) - 1536-dimensional vector to compresscompression_ratio(number, optional) - Target ratio 0-1 (default: 0.5)algorithm(string, optional) - Algorithm: "qaoa" or "vqe" (default: "qaoa")
Returns:
{
"compressed_vector": [...],
"original_dimensions": 1536,
"compressed_dimensions": 768,
"compression_ratio": 0.5,
"fidelity_score": 0.98
}
Example:
{
"vector_embedding": [...],
"compression_ratio": 0.6,
"algorithm": "qaoa"
}
15. zerodb_quantum_decompress
Decompress quantum-compressed vector.
Parameters:
compressed_vector(array[number], required) - Compressed vector dataoriginal_dimensions(number, required) - Original dimension count
Returns:
{
"decompressed_vector": [...],
"dimensions": 1536,
"reconstruction_error": 0.02
}
Example:
{
"compressed_vector": [...],
"original_dimensions": 1536
}
16. zerodb_quantum_hybrid_search
Perform hybrid search using quantum-enhanced similarity.
Parameters:
query_vector(array[number], required) - 1536-dimensional querynamespace(string, optional) - Vector namespacelimit(number, optional) - Max results (default: 10)quantum_weight(number, optional) - Quantum influence 0-1 (default: 0.5)
Returns:
{
"vectors": [
{
"vector_id": "uuid",
"document": "string",
"similarity_score": 0.96,
"quantum_score": 0.94,
"hybrid_score": 0.95
}
]
}
Example:
{
"query_vector": [...],
"namespace": "windsurf",
"limit": 10,
"quantum_weight": 0.7
}
17. zerodb_quantum_optimize
Optimize vector space using quantum optimization.
Parameters:
namespace(string, required) - Namespace to optimizeoptimization_target(string, optional) - "storage" or "search_speed" (default: "storage")
Returns:
{
"optimized": true,
"improvement_percentage": 35.5,
"duration_ms": 5000
}
Example:
{
"namespace": "windsurf",
"optimization_target": "search_speed"
}
18. zerodb_quantum_feature_map
Generate quantum feature map for vector.
Parameters:
vector_embedding(array[number], required) - 1536-dimensional vectorfeature_map_type(string, optional) - "zz" or "pauli" (default: "zz")
Returns:
{
"feature_map": [...],
"quantum_circuit_depth": 10,
"qubit_count": 12
}
Example:
{
"vector_embedding": [...],
"feature_map_type": "pauli"
}
19. zerodb_quantum_kernel
Compute quantum kernel similarity between vectors.
Parameters:
vector_a(array[number], required) - First 1536-dimensional vectorvector_b(array[number], required) - Second 1536-dimensional vectorkernel_type(string, optional) - "linear" or "rbf" (default: "rbf")
Returns:
{
"kernel_similarity": 0.92,
"quantum_advantage": 0.15,
"computation_time_ms": 45
}
Example:
{
"vector_a": [...],
"vector_b": [...],
"kernel_type": "rbf"
}
Table/NoSQL Operations
20. zerodb_create_table
Create a new NoSQL table with schema.
Parameters:
table_name(string, required) - Table nameschema(object, required) - JSON schema definitiondescription(string, optional) - Table description
Returns:
{
"table_id": "uuid",
"table_name": "string",
"created_at": "timestamp"
}
Example:
{
"table_name": "user_profiles",
"schema": {
"user_id": "uuid",
"name": "string",
"email": "string",
"created_at": "timestamp"
},
"description": "User profile information"
}
21. zerodb_list_tables
List all tables in project.
Parameters:
limit(number, optional) - Results per page (default: 50)offset(number, optional) - Pagination offset (default: 0)
Returns:
{
"tables": [
{
"table_id": "uuid",
"table_name": "string",
"row_count": 1000,
"created_at": "timestamp"
}
],
"total_count": 10
}
Example:
{
"limit": 100,
"offset": 0
}
22. zerodb_get_table
Get table details and schema.
Parameters:
table_id(string, required) - Table UUID
Returns:
{
"table_id": "uuid",
"table_name": "string",
"schema": {},
"row_count": 1000,
"created_at": "timestamp"
}
Example:
{
"table_id": "123e4567-e89b-12d3-a456-426614174000"
}
23. zerodb_delete_table
Delete a table and all its data.
Parameters:
table_id(string, required) - Table UUID to delete
Returns:
{
"success": true,
"deleted_id": "uuid",
"rows_deleted": 1000
}
Example:
{
"table_id": "123e4567-e89b-12d3-a456-426614174000"
}
24. zerodb_insert_rows
Insert rows into table.
Parameters:
table_id(string, required) - Table UUIDrows(array, required) - Array of row objects
Returns:
{
"inserted_count": 100,
"row_ids": ["uuid1", "uuid2", ...]
}
Example:
{
"table_id": "123e4567-e89b-12d3-a456-426614174000",
"rows": [
{
"user_id": "user-1",
"name": "John Doe",
"email": "john@example.com"
},
{
"user_id": "user-2",
"name": "Jane Smith",
"email": "jane@example.com"
}
]
}
25. zerodb_query_rows
Query table rows with filters.
Parameters:
table_id(string, required) - Table UUIDfilters(object, optional) - Query filterslimit(number, optional) - Max results (default: 50)offset(number, optional) - Pagination offset (default: 0)
Returns:
{
"rows": [...],
"total_count": 1000,
"limit": 50,
"offset": 0
}
Example:
{
"table_id": "123e4567-e89b-12d3-a456-426614174000",
"filters": {
"email": {
"$contains": "@example.com"
}
},
"limit": 100
}
26. zerodb_update_rows
Update rows in table.
Parameters:
table_id(string, required) - Table UUIDfilters(object, required) - Row selection filtersupdates(object, required) - Fields to update
Returns:
{
"updated_count": 50,
"row_ids": ["uuid1", "uuid2", ...]
}
Example:
{
"table_id": "123e4567-e89b-12d3-a456-426614174000",
"filters": {
"user_id": "user-1"
},
"updates": {
"email": "newemail@example.com"
}
}
27. zerodb_delete_rows
Delete rows from table.
Parameters:
table_id(string, required) - Table UUIDfilters(object, required) - Row selection filters
Returns:
{
"deleted_count": 25,
"row_ids": ["uuid1", "uuid2", ...]
}
Example:
{
"table_id": "123e4567-e89b-12d3-a456-426614174000",
"filters": {
"created_at": {
"$lt": "2025-01-01"
}
}
}
File Operations
28. zerodb_upload_file
Upload file to ZeroDB storage.
Parameters:
file_name(string, required) - File namefile_data(string, required) - Base64-encoded file datacontent_type(string, optional) - MIME typemetadata(object, optional) - File metadata
Returns:
{
"file_id": "uuid",
"file_name": "string",
"size_bytes": 1024,
"upload_url": "string"
}
Example:
{
"file_name": "document.pdf",
"file_data": "base64encodeddata...",
"content_type": "application/pdf",
"metadata": {
"category": "documentation"
}
}
29. zerodb_download_file
Download file from ZeroDB storage.
Parameters:
file_id(string, required) - File UUID
Returns:
{
"file_id": "uuid",
"file_name": "string",
"file_data": "base64encodeddata...",
"content_type": "string",
"size_bytes": 1024
}
Example:
{
"file_id": "123e4567-e89b-12d3-a456-426614174000"
}
30. zerodb_list_files
List files with pagination.
Parameters:
limit(number, optional) - Results per page (default: 50)offset(number, optional) - Pagination offset (default: 0)content_type(string, optional) - Filter by MIME type
Returns:
{
"files": [
{
"file_id": "uuid",
"file_name": "string",
"size_bytes": 1024,
"content_type": "string",
"created_at": "timestamp"
}
],
"total_count": 100
}
Example:
{
"limit": 100,
"content_type": "application/pdf"
}
31. zerodb_delete_file
Delete file from storage.
Parameters:
file_id(string, required) - File UUID to delete
Returns:
{
"success": true,
"deleted_id": "uuid"
}
Example:
{
"file_id": "123e4567-e89b-12d3-a456-426614174000"
}
32. zerodb_get_file_metadata
Get file metadata without downloading.
Parameters:
file_id(string, required) - File UUID
Returns:
{
"file_id": "uuid",
"file_name": "string",
"size_bytes": 1024,
"content_type": "string",
"metadata": {},
"created_at": "timestamp"
}
Example:
{
"file_id": "123e4567-e89b-12d3-a456-426614174000"
}
33. zerodb_generate_presigned_url
Generate temporary download URL.
Parameters:
file_id(string, required) - File UUIDexpiry_seconds(number, optional) - URL validity (default: 3600)
Returns:
{
"file_id": "uuid",
"presigned_url": "https://...",
"expires_at": "timestamp"
}
Example:
{
"file_id": "123e4567-e89b-12d3-a456-426614174000",
"expiry_seconds": 7200
}
Event Operations
34. zerodb_create_event
Create a new event in the event system.
Parameters:
event_type(string, required) - Event type identifierevent_data(object, required) - Event payloadmetadata(object, optional) - Event metadata
Returns:
{
"event_id": "uuid",
"event_type": "string",
"created_at": "timestamp"
}
Example:
{
"event_type": "user.signup",
"event_data": {
"user_id": "user-123",
"email": "user@example.com"
},
"metadata": {
"source": "web"
}
}
35. zerodb_list_events
List events with filtering and pagination.
Parameters:
event_type(string, optional) - Filter by event typestart_date(string, optional) - Filter by start date (ISO 8601)end_date(string, optional) - Filter by end date (ISO 8601)limit(number, optional) - Results per page (default: 50)offset(number, optional) - Pagination offset (default: 0)
Returns:
{
"events": [
{
"event_id": "uuid",
"event_type": "string",
"event_data": {},
"created_at": "timestamp"
}
],
"total_count": 1000
}
Example:
{
"event_type": "user.signup",
"start_date": "2025-10-01T00:00:00Z",
"limit": 100
}
36. zerodb_get_event
Get specific event by ID.
Parameters:
event_id(string, required) - Event UUID
Returns:
{
"event_id": "uuid",
"event_type": "string",
"event_data": {},
"metadata": {},
"created_at": "timestamp"
}
Example:
{
"event_id": "123e4567-e89b-12d3-a456-426614174000"
}
37. zerodb_subscribe_events
Subscribe to event stream (WebSocket).
Parameters:
event_types(array[string], required) - Event types to subscribe tofilters(object, optional) - Additional filters
Returns:
{
"subscription_id": "uuid",
"event_types": ["user.signup", "user.login"],
"websocket_url": "wss://..."
}
Example:
{
"event_types": ["user.signup", "user.login"],
"filters": {
"source": "web"
}
}
38. zerodb_event_stats
Get event statistics and analytics.
Parameters:
event_type(string, optional) - Filter by event typestart_date(string, optional) - Start date (ISO 8601)end_date(string, optional) - End date (ISO 8601)group_by(string, optional) - Group by: "hour", "day", "week" (default: "day")
Returns:
{
"total_events": 10000,
"event_types": {
"user.signup": 1000,
"user.login": 9000
},
"timeline": [
{
"date": "2025-10-14",
"count": 500
}
]
}
Example:
{
"start_date": "2025-10-01T00:00:00Z",
"end_date": "2025-10-14T23:59:59Z",
"group_by": "day"
}
Project Operations
39. zerodb_create_project
Create a new ZeroDB project.
Parameters:
project_name(string, required) - Project namedescription(string, optional) - Project descriptionsettings(object, optional) - Project settings
Returns:
{
"project_id": "uuid",
"project_name": "string",
"created_at": "timestamp"
}
Example:
{
"project_name": "My AI Application",
"description": "Vector search for customer support",
"settings": {
"retention_days": 90
}
}
40. zerodb_get_project
Get project details.
Parameters:
project_id(string, required) - Project UUID
Returns:
{
"project_id": "uuid",
"project_name": "string",
"description": "string",
"settings": {},
"created_at": "timestamp"
}
Example:
{
"project_id": "123e4567-e89b-12d3-a456-426614174000"
}
41. zerodb_list_projects
List all accessible projects.
Parameters:
limit(number, optional) - Results per page (default: 50)offset(number, optional) - Pagination offset (default: 0)
Returns:
{
"projects": [
{
"project_id": "uuid",
"project_name": "string",
"created_at": "timestamp"
}
],
"total_count": 10
}
Example:
{
"limit": 100
}
42. zerodb_update_project
Update project settings.
Parameters:
project_id(string, required) - Project UUIDproject_name(string, optional) - New project namedescription(string, optional) - New descriptionsettings(object, optional) - Updated settings
Returns:
{
"project_id": "uuid",
"updated_fields": ["project_name", "settings"],
"updated_at": "timestamp"
}
Example:
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"settings": {
"retention_days": 120
}
}
43. zerodb_delete_project
Delete a project and all its data.
Parameters:
project_id(string, required) - Project UUID to deleteconfirm(boolean, required) - Must be true to confirm deletion
Returns:
{
"success": true,
"deleted_id": "uuid",
"deleted_at": "timestamp"
}
Example:
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"confirm": true
}
44. zerodb_get_project_stats
Get project usage statistics.
Parameters:
project_id(string, required) - Project UUIDstart_date(string, optional) - Start date (ISO 8601)end_date(string, optional) - End date (ISO 8601)
Returns:
{
"project_id": "uuid",
"vector_count": 10000,
"memory_count": 5000,
"table_count": 10,
"file_count": 100,
"storage_bytes": 10485760,
"api_calls": 50000
}
Example:
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"start_date": "2025-10-01T00:00:00Z"
}
45. zerodb_enable_database
Enable database features for project.
Parameters:
project_id(string, required) - Project UUIDfeatures(array[string], required) - Features to enable: ["vectors", "tables", "files", "events"]
Returns:
{
"project_id": "uuid",
"enabled_features": ["vectors", "tables"],
"enabled_at": "timestamp"
}
Example:
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"features": ["vectors", "tables", "files"]
}
RLHF Operations
46. zerodb_rlhf_interaction
Collect user interaction for RLHF training.
Parameters:
session_id(string, required) - Session identifieruser_input(string, required) - User's inputagent_response(string, required) - Agent's responsefeedback_score(number, optional) - User rating 1-5metadata(object, optional) - Additional context
Returns:
{
"interaction_id": "uuid",
"collected_at": "timestamp"
}
Example:
{
"session_id": "session-123",
"user_input": "How do I reset my password?",
"agent_response": "You can reset your password by...",
"feedback_score": 5,
"metadata": {
"model": "claude-3-sonnet",
"response_time_ms": 1200
}
}
47. zerodb_rlhf_agent_feedback
Collect feedback about agent performance.
Parameters:
agent_id(string, required) - Agent identifiersession_id(string, required) - Session identifierfeedback_type(string, required) - "positive" or "negative"feedback_text(string, optional) - Detailed feedbackmetrics(object, optional) - Performance metrics
Returns:
{
"feedback_id": "uuid",
"collected_at": "timestamp"
}
Example:
{
"agent_id": "agent-123",
"session_id": "session-123",
"feedback_type": "positive",
"feedback_text": "Very helpful and accurate responses",
"metrics": {
"accuracy": 0.95,
"helpfulness": 0.9
}
}
48. zerodb_rlhf_workflow
Collect feedback about workflow completion.
Parameters:
workflow_id(string, required) - Workflow identifiersession_id(string, required) - Session identifiercompleted(boolean, required) - Workflow completion statusduration_ms(number, optional) - Workflow durationfeedback(object, optional) - Workflow feedback
Returns:
{
"workflow_feedback_id": "uuid",
"collected_at": "timestamp"
}
Example:
{
"workflow_id": "workflow-123",
"session_id": "session-123",
"completed": true,
"duration_ms": 5000,
"feedback": {
"ease_of_use": 5,
"effectiveness": 4
}
}
49. zerodb_rlhf_error
Collect error reports for model improvement.
Parameters:
session_id(string, required) - Session identifiererror_type(string, required) - Error categoryerror_message(string, required) - Error descriptioncontext(object, optional) - Error contextuser_impact(string, optional) - Impact level: "low", "medium", "high"
Returns:
{
"error_report_id": "uuid",
"collected_at": "timestamp"
}
Example:
{
"session_id": "session-123",
"error_type": "hallucination",
"error_message": "Agent provided incorrect information about product pricing",
"context": {
"user_query": "What is the price?",
"agent_response": "The price is $50"
},
"user_impact": "high"
}
50. zerodb_rlhf_status
Get RLHF collection status.
Parameters:
session_id(string, optional) - Filter by sessionstart_date(string, optional) - Start date (ISO 8601)end_date(string, optional) - End date (ISO 8601)
Returns:
{
"total_interactions": 1000,
"avg_feedback_score": 4.2,
"positive_feedback": 850,
"negative_feedback": 150,
"collection_rate": 0.85
}
Example:
{
"start_date": "2025-10-01T00:00:00Z",
"end_date": "2025-10-14T23:59:59Z"
}
51. zerodb_rlhf_summary
Get RLHF analytics summary.
Parameters:
group_by(string, optional) - Group by: "agent", "workflow", "session" (default: "agent")start_date(string, optional) - Start date (ISO 8601)end_date(string, optional) - End date (ISO 8601)
Returns:
{
"summary": [
{
"group_id": "agent-123",
"interaction_count": 500,
"avg_score": 4.5,
"improvement_trend": 0.15
}
]
}
Example:
{
"group_by": "agent",
"start_date": "2025-10-01T00:00:00Z"
}
52. zerodb_rlhf_start
Start RLHF collection for session.
Parameters:
session_id(string, required) - Session identifiercollection_config(object, optional) - Collection settings
Returns:
{
"session_id": "uuid",
"collection_started": true,
"started_at": "timestamp"
}
Example:
{
"session_id": "session-123",
"collection_config": {
"collect_all_interactions": true,
"require_explicit_feedback": false
}
}
53. zerodb_rlhf_stop
Stop RLHF collection for session.
Parameters:
session_id(string, required) - Session identifier
Returns:
{
"session_id": "uuid",
"collection_stopped": true,
"stopped_at": "timestamp",
"total_collected": 50
}
Example:
{
"session_id": "session-123"
}
54. zerodb_rlhf_session
Get all interactions for a session.
Parameters:
session_id(string, required) - Session identifierlimit(number, optional) - Max results (default: 100)
Returns:
{
"session_id": "uuid",
"interactions": [
{
"interaction_id": "uuid",
"user_input": "string",
"agent_response": "string",
"feedback_score": 5,
"timestamp": "timestamp"
}
],
"total_count": 50
}
Example:
{
"session_id": "session-123",
"limit": 200
}
55. zerodb_rlhf_broadcast
Broadcast RLHF event to subscribers.
Parameters:
event_type(string, required) - Event typeevent_data(object, required) - Event payloadtarget_sessions(array[string], optional) - Target session IDs
Returns:
{
"broadcast_id": "uuid",
"recipients": 10,
"broadcasted_at": "timestamp"
}
Example:
{
"event_type": "feedback.requested",
"event_data": {
"interaction_id": "interaction-123",
"question": "Was this response helpful?"
},
"target_sessions": ["session-1", "session-2"]
}
Admin Operations
56. zerodb_admin_system_stats
Get system-wide statistics (requires admin role).
Parameters:
include_details(boolean, optional) - Include detailed metrics (default: false)
Returns:
{
"total_projects": 100,
"total_users": 500,
"total_vectors": 1000000,
"total_storage_bytes": 10737418240,
"active_sessions": 50,
"api_calls_24h": 100000,
"avg_response_time_ms": 150
}
Example:
{
"include_details": true
}
57. zerodb_admin_list_projects
List all projects in system (requires admin role).
Parameters:
user_id(string, optional) - Filter by userlimit(number, optional) - Results per page (default: 100)offset(number, optional) - Pagination offset (default: 0)
Returns:
{
"projects": [
{
"project_id": "uuid",
"project_name": "string",
"user_id": "uuid",
"created_at": "timestamp",
"storage_bytes": 1048576
}
],
"total_count": 100
}
Example:
{
"limit": 500
}
58. zerodb_admin_user_usage
Get user usage statistics (requires admin role).
Parameters:
user_id(string, required) - User UUIDstart_date(string, optional) - Start date (ISO 8601)end_date(string, optional) - End date (ISO 8601)
Returns:
{
"user_id": "uuid",
"project_count": 5,
"vector_count": 10000,
"storage_bytes": 10485760,
"api_calls": 50000,
"cost_estimate_usd": 25.50
}
Example:
{
"user_id": "user-123",
"start_date": "2025-10-01T00:00:00Z"
}
59. zerodb_admin_health
Get system health status (requires admin role).
Parameters:
- None
Returns:
{
"status": "healthy",
"database": "connected",
"storage": "healthy",
"quantum_service": "operational",
"cache": "healthy",
"uptime_seconds": 86400,
"last_check": "timestamp"
}
Example:
{}
60. zerodb_admin_optimize
Optimize database and storage (requires admin role).
Parameters:
optimization_type(string, required) - "vacuum", "reindex", or "all"tables(array[string], optional) - Specific tables to optimize
Returns:
{
"optimized": true,
"optimization_type": "all",
"duration_ms": 30000,
"space_freed_bytes": 1048576,
"improvements": {
"query_performance": 0.25,
"storage_efficiency": 0.15
}
}
Example:
{
"optimization_type": "all"
}
PostgreSQL Operations
Dedicated PostgreSQL database operations for advanced SQL workloads.
61. zerodb_postgres_query
Execute SQL query on your provisioned PostgreSQL instance with comprehensive security validations.
Parameters:
sql(string, required) - SQL query to executeparams(array[string], optional) - Query parameters for prepared statementsread_only(boolean, optional) - Enforce read-only mode (SELECT only), default: falsetimeout_seconds(number, optional) - Query timeout in seconds, default: 30max_rows(number, optional) - Maximum rows to return, default: 1000
Returns:
{
"query_id": "q_abc123",
"query_type": "SELECT",
"rows_returned": 10,
"rows_affected": 0,
"execution_time_ms": 45.2,
"columns": ["id", "name", "email"],
"rows": [{"id": 1, "name": "User", "email": "user@example.com"}],
"success": true
}
Security Features:
- SQL injection prevention (blocks DROP DATABASE, TRUNCATE, etc.)
- Query timeout enforcement
- Read-only mode support
- Parameter sanitization
- Execution history tracking
Example:
{
"sql": "SELECT * FROM users WHERE created_at > $1 LIMIT 10",
"params": ["2025-01-01"],
"read_only": true,
"timeout_seconds": 30
}
62. zerodb_postgres_schema_info
Get detailed database schema information including tables, columns, indexes, and constraints.
Parameters:
table_name(string, optional) - Specific table to inspect (omit for all tables)include_indexes(boolean, optional) - Include index information, default: trueinclude_constraints(boolean, optional) - Include constraint information, default: trueinclude_stats(boolean, optional) - Include table statistics, default: false
Returns:
{
"schema": "public",
"total_tables": 5,
"database_size_mb": 150.5,
"tables": [
{
"table_name": "users",
"columns": [
{"name": "id", "type": "INTEGER", "nullable": false, "primary_key": true},
{"name": "email", "type": "VARCHAR(255)", "nullable": false, "unique": true}
],
"indexes": [
{"name": "users_pkey", "columns": ["id"], "unique": true},
{"name": "users_email_idx", "columns": ["email"], "unique": true}
],
"row_count": 1000,
"size_mb": 25.5
}
]
}
Example:
{
"table_name": "users",
"include_indexes": true,
"include_constraints": true
}
63. zerodb_postgres_create_table
Create a new table with complete schema definition including columns, constraints, and indexes.
Parameters:
table_name(string, required) - Name of the table to createcolumns(array, required) - Column definitionsname(string, required) - Column nametype(string, required) - Column type (e.g., "VARCHAR(255)", "INTEGER", "TIMESTAMP")nullable(boolean, optional) - Allow NULL values, default: trueprimary_key(boolean, optional) - Is primary key, default: falseunique(boolean, optional) - Unique constraint, default: falsedefault(string, optional) - Default value
indexes(array, optional) - Index definitionsname(string, optional) - Index name (auto-generated if not provided)columns(array[string], required) - Columns to indexunique(boolean, optional) - Unique index, default: false
if_not_exists(boolean, optional) - Only create if table doesn't exist, default: true
Returns:
{
"table_name": "products",
"created": true,
"columns_count": 5,
"indexes_created": 2,
"indexes": [
{"index_name": "products_sku_idx", "success": true},
{"index_name": "products_name_idx", "success": true}
]
}
Example:
{
"table_name": "products",
"columns": [
{"name": "id", "type": "SERIAL", "primary_key": true},
{"name": "sku", "type": "VARCHAR(50)", "nullable": false, "unique": true},
{"name": "name", "type": "VARCHAR(255)", "nullable": false},
{"name": "price", "type": "DECIMAL(10,2)", "nullable": false},
{"name": "created_at", "type": "TIMESTAMP", "default": "NOW()"}
],
"indexes": [
{"columns": ["sku"], "unique": true},
{"columns": ["name"]}
]
}
64. zerodb_postgres_backup
Trigger a PostgreSQL backup job with configurable options.
Parameters:
backup_type(string, optional) - "full" or "incremental", default: "full"retention_days(number, optional) - Backup retention in days, default: 7compression(boolean, optional) - Compress backup, default: trueinclude_schema(boolean, optional) - Include schema definition, default: trueinclude_data(boolean, optional) - Include table data, default: true
Returns:
{
"backup_id": "backup_xyz789",
"backup_type": "full",
"status": "initiated",
"estimated_size_mb": 250.0,
"retention_days": 7,
"created_at": "2025-12-07T18:00:00Z"
}
Example:
{
"backup_type": "full",
"retention_days": 30,
"compression": true
}
65. zerodb_postgres_restore
Restore PostgreSQL database from a backup.
Parameters:
backup_id(string, required) - Backup ID to restore fromrestore_type(string, optional) - "full", "schema_only", or "data_only", default: "full"target_database(string, optional) - Restore to different database nameconfirm_overwrite(boolean, required) - Must be true to confirm overwrite of existing data
Returns:
{
"restore_id": "restore_abc123",
"backup_id": "backup_xyz789",
"status": "in_progress",
"estimated_time_minutes": 5,
"started_at": "2025-12-07T18:05:00Z"
}
Security:
- Requires explicit
confirm_overwrite: trueto prevent accidental data loss - Logs all restore operations for audit trail
Example:
{
"backup_id": "backup_xyz789",
"restore_type": "full",
"confirm_overwrite": true
}
66. zerodb_postgres_stats
Get comprehensive PostgreSQL database statistics including performance metrics.
Parameters:
include_connections(boolean, optional) - Include connection statistics, default: trueinclude_queries(boolean, optional) - Include query performance stats, default: trueinclude_storage(boolean, optional) - Include storage statistics, default: trueinclude_replication(boolean, optional) - Include replication stats, default: falsetime_range(string, optional) - "hour", "day", "week", or "month", default: "day"
Returns:
{
"project_id": "proj_123",
"database_size_mb": 150.5,
"table_count": 25,
"active_connections": 5,
"max_connections": 100,
"queries_per_second": 120.5,
"cache_hit_ratio": 0.95,
"avg_query_time_ms": 15.2,
"cpu_usage_percent": 25.0,
"memory_usage_percent": 40.0,
"replication_lag_ms": null
}
Example:
{
"include_connections": true,
"include_queries": true,
"include_storage": true,
"time_range": "day"
}
Configuration
Environment Variables
All configuration is done through environment variables. Set these in your MCP server configuration.
| Variable | Required | Default | Description |
|---|---|---|---|
ZERODB_API_URL | No | https://api.ainative.studio | ZeroDB API base URL |
ZERODB_PROJECT_ID | Yes | - | Your ZeroDB project ID |
ZERODB_USERNAME | Yes | - | Your ZeroDB account email |
ZERODB_PASSWORD | Yes | - | Your ZeroDB account password |
ZERODB_API_TOKEN | No | - | Pre-existing API token (optional, will be auto-generated) |
MCP_CONTEXT_WINDOW | No | 8192 | Maximum tokens in context window |
MCP_RETENTION_DAYS | No | 30 | Memory retention period in days |
Authentication
The MCP server uses JWT authentication with automatic token renewal:
- Initial Authentication: On startup, the server authenticates using username/password
- Token Storage: Access token is stored in memory
- Automatic Renewal: Token is automatically renewed every 25 minutes (tokens expire after 30 minutes)
- Manual Renewal: Use
zerodb_renew_tokento manually renew if needed
Security Best Practices
- Store credentials securely: Use environment variables, never hardcode
- Use project-specific credentials: Create separate projects for different applications
- Rotate passwords regularly: Change passwords every 90 days
- Monitor API usage: Check for unusual activity in project stats
- Limit token scope: Use project-specific tokens when possible
Examples
Example 1: Building a Knowledge Base
// 1. Create a project for your knowledge base
const project = await zerodb_create_project({
project_name: "Product Documentation KB",
description: "Searchable product documentation"
});
// 2. Upload documentation files
const file = await zerodb_upload_file({
file_name: "user_guide.pdf",
file_data: "base64data...",
content_type: "application/pdf"
});
// 3. Store vectors for semantic search
// (Assume you've generated embeddings from the documentation)
const vector = await zerodb_store_vector({
vector_embedding: [...], // 1536-dimensional vector
document: "How to reset your password: Navigate to Settings...",
metadata: {
source: "user_guide.pdf",
page: 15
}
});
// 4. Search the knowledge base
const results = await zerodb_search_vectors({
query_vector: [...], // User query embedding
limit: 5,
threshold: 0.75
});
Example 2: Agent Memory with Context
// 1. Store conversation in memory
await zerodb_store_memory({
content: "User wants to book a flight to Paris",
role: "user",
session_id: "session-123"
});
await zerodb_store_memory({
content: "I'll help you book a flight to Paris. What dates?",
role: "assistant",
session_id: "session-123"
});
// 2. Later in the conversation, get context
const context = await zerodb_get_context({
session_id: "session-123",
max_tokens: 4096
});
// Context includes all previous messages, token-optimized
Example 3: RLHF Data Collection
// 1. Start RLHF collection for session
await zerodb_rlhf_start({
session_id: "session-456",
collection_config: {
collect_all_interactions: true
}
});
// 2. Collect interactions during conversation
await zerodb_rlhf_interaction({
session_id: "session-456",
user_input: "What's the weather like?",
agent_response: "I don't have access to real-time weather data",
feedback_score: 3,
metadata: {
model: "claude-3-sonnet",
response_time_ms: 800
}
});
// 3. Collect error reports
await zerodb_rlhf_error({
session_id: "session-456",
error_type: "capability_limitation",
error_message: "Agent cannot access real-time data",
user_impact: "medium"
});
// 4. Get RLHF summary
const summary = await zerodb_rlhf_summary({
group_by: "session",
start_date: "2025-10-14T00:00:00Z"
});
Example 4: Quantum-Enhanced Search
// 1. Store vectors with quantum compression
const compressed = await zerodb_quantum_compress({
vector_embedding: [...], // Original 1536 dimensions
compression_ratio: 0.5,
algorithm: "qaoa"
});
// Store compressed version
await zerodb_store_vector({
vector_embedding: compressed.compressed_vector,
document: "Product description...",
metadata: {
compressed: true,
original_dimensions: 1536
}
});
// 2. Perform quantum hybrid search
const results = await zerodb_quantum_hybrid_search({
query_vector: [...],
quantum_weight: 0.7, // Higher weight for quantum similarity
limit: 10
});
// Results include both classical and quantum similarity scores
Example 5: NoSQL Data Management
// 1. Create a table for user profiles
const table = await zerodb_create_table({
table_name: "user_profiles",
schema: {
user_id: "uuid",
name: "string",
email: "string",
preferences: "json",
created_at: "timestamp"
}
});
// 2. Insert user data
await zerodb_insert_rows({
table_id: table.table_id,
rows: [
{
user_id: "user-1",
name: "Alice Smith",
email: "alice@example.com",
preferences: { theme: "dark", language: "en" }
}
]
});
// 3. Query users
const users = await zerodb_query_rows({
table_id: table.table_id,
filters: {
email: { $contains: "@example.com" }
}
});
// 4. Update preferences
await zerodb_update_rows({
table_id: table.table_id,
filters: { user_id: "user-1" },
updates: {
preferences: { theme: "light", language: "en" }
}
});
Example 6: Error Handling
// All operations return structured responses with error handling
try {
const result = await zerodb_store_vector({
vector_embedding: [...],
document: "Sample text"
});
if (result.isError) {
console.error("Operation failed:", result.content[0].text);
// Handle error appropriately
} else {
console.log("Success:", result.content[0].text);
}
} catch (error) {
// Handle unexpected errors
console.error("Unexpected error:", error.message);
}
Migration Guide
Migrating from v1.x to v2.0.0
Breaking Changes
-
API Endpoint Consolidation
- v1.x: Direct API calls to various endpoints
- v2.0: All operations go through unified MCP execute endpoint
Impact: No code changes needed if using MCP tools
-
Tool Naming Convention
- v1.x: Some tools lacked
zerodb_prefix - v2.0: All tools prefixed with
zerodb_
Migration:
// Old (v1.x) store_memory(...) → zerodb_store_memory(...) search_memory(...) → zerodb_search_memory(...) // New (v2.0) zerodb_store_memory(...) // Consistent prefix - v1.x: Some tools lacked
-
Parameter Changes
- Memory operations:
memory_metadata→metadata - Vector operations:
vector_metadata→metadata
Migration:
// Old (v1.x) { content: "...", memory_metadata: { key: "value" } } // New (v2.0) { content: "...", metadata: { key: "value" } } - Memory operations:
-
New Required Environment Variables
ZERODB_PROJECT_IDis now required (was optional in v1.x)
Migration: Add to your config:
{ "env": { "ZERODB_PROJECT_ID": "your-project-id" } }
New Features Available
- 54 New Operations - Full API coverage beyond memory and vector operations
- Quantum Compression - Reduce vector storage by up to 50%
- NoSQL Tables - Structured data storage and queries
- File Management - Upload and manage files
- Event System - Event-driven architecture support
- RLHF Collection - Built-in feedback collection for model training
- Admin Tools - System monitoring and optimization
Migration Steps
-
Update Package
npm update ainative-zerodb-mcp-server # or npm install -g ainative-zerodb-mcp-server@2.0.0 -
Update Configuration
- Add
ZERODB_PROJECT_IDto environment variables - Update any custom tool names to include
zerodb_prefix
- Add
-
Test Existing Functionality
- All v1.x operations remain compatible
- Test memory and vector operations still work
-
Gradually Adopt New Features
- Start with new features that provide immediate value
- Refer to API Reference for new operation documentation
Backward Compatibility
- All v1.x operations are supported in v2.0
- Existing data and projects are fully compatible
- No data migration required
Troubleshooting
Common Issues
1. Authentication Failed
Error: Authentication failed: Invalid credentials
Solutions:
- Verify
ZERODB_USERNAMEandZERODB_PASSWORDare correct - Check that your account is active
- Try manual token renewal:
zerodb_renew_token
2. Project Not Found
Error: Project not found: [project-id]
Solutions:
- Verify
ZERODB_PROJECT_IDis correct - List your projects:
zerodb_list_projects - Create a new project:
zerodb_create_project
3. Vector Dimension Mismatch
Error: vector must have exactly 1536 dimensions, got 768
Solutions:
- Ensure you're using OpenAI's
text-embedding-3-small(1536 dimensions) - Or use
text-embedding-ada-002(1536 dimensions) - Do not use
text-embedding-3-large(3072 dimensions)
4. Token Expired
Error: Token expired or invalid
Solutions:
- The server should auto-renew tokens every 25 minutes
- Manually renew:
zerodb_renew_token - Check server logs for renewal errors
5. Rate Limiting
Error: Rate limit exceeded
Solutions:
- Reduce request frequency
- Use batch operations where available
- Contact support for rate limit increases
Debug Logging
Enable verbose logging by checking stderr output:
# The MCP server logs to stderr
# In Claude Desktop, check: ~/Library/Logs/Claude/mcp*.log
Log messages include:
- Token renewal attempts and status
- API call details (operation, params)
- Error messages with full context
Getting Help
- Documentation: https://docs.ainative.studio/zerodb
- GitHub Issues: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues
- Email Support: support@ainative.studio
- Discord Community: https://discord.gg/ainative
Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
# Clone repository
git clone https://github.com/AINative-Studio/ainative-zerodb-mcp-server.git
cd ainative-zerodb-mcp-server
# Install dependencies
npm install
# Run tests
npm test
# Lint code
npm run lint
# Run security audit
npm run security:audit
Testing
# Run tests with coverage
npm test
# Watch mode for development
npm run test:watch
# CI mode
npm run test:ci
Code Quality
- 90%+ test coverage required
- ESLint for code style
- No high/critical npm vulnerabilities
- All tests must pass before PR merge
License
MIT License - see LICENSE file for details.
Changelog
v2.0.0 (2025-10-14)
Breaking Changes:
- All operations now require
ZERODB_PROJECT_IDenvironment variable - Unified API endpoint for all operations
- Consistent
zerodb_prefix for all tool names
New Features:
- Added 54 new operations (total 60)
- Quantum vector compression and optimization
- NoSQL table operations
- File storage and management
- Event-driven architecture support
- RLHF feedback collection
- Admin system monitoring and optimization
- 90%+ test coverage
- Automatic token renewal
Improvements:
- Better error handling and messages
- Improved documentation
- Enhanced security
- Performance optimizations
v1.0.7 (2025-10-01)
- Initial public release
- Basic memory and vector operations
- Claude Desktop integration
Built with ❤️ by AINative Studio
Powered by ZeroDB - Enterprise Vector Search for AI