ZeroDB MCP Server v2.3.2

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.3.2

• Auth endpoint fix — login uses /v1/auth/login with email field (was broken in v2.2.0)

• Execute endpoint fix — all MCP operations route through /v1/public/mcp (was dead endpoint)

• PostgreSQL endpoint fix — all 7 postgres management paths corrected

• Test env isolation fix — 151/151 tests passing with proper env var cleanup

• 3 Embedding Tools (from v2.2.0) — zerodb_generate_embeddings, zerodb_embed_and_store, zerodb_semantic_search

• Multi-Dimension Support — 384, 768, 1024, or 1536 dimension vectors

• Free Models — BAAI/bge-small/base/large-en-v1.5 (no API costs)

• See EMBEDDING_TOOLS_GUIDE.md for complete documentation

Related MCP server: MCP Memory Server

Key Features

• 70+ Complete Operations - Full API coverage across all ZeroDB capabilities including 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

  • Memory Operations (3)

  • Vector Operations (10)

  • Quantum Operations (6)

  • Table/NoSQL Operations (8)

  • File Operations (6)

  • Event Operations (5)

  • Project Operations (7)

  • RLHF Operations (10)

  • Admin Operations (5)

  • PostgreSQL Operations (6)

• 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

1. Click on "Register User" endpoint

2. Use the "Try it out" feature

3. 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/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "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_API_KEY": "your-api-key",
        "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 store

• role (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 query

• session_id (string, optional) - Filter by session

• agent_id (string, optional) - Filter by agent

• role (string, optional) - Filter by role

• limit (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 identifier

• agent_id (string, optional) - Agent identifier

• max_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 vector

• document (string, required) - Source document text

• metadata (object, optional) - Document metadata

• namespace (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 objects

  • vector_embedding (array[number], required) - 1536-dimensional vector

  • document (string, required) - Source document

  • metadata (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 vector

• namespace (string, optional) - Vector namespace

• limit (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 namespace

• limit (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 index

• index_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 export

• format (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 compress

• compression_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 data

• original_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 query

• namespace (string, optional) - Vector namespace

• limit (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 optimize

• optimization_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 vector

• feature_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 vector

• vector_b (array[number], required) - Second 1536-dimensional vector

• kernel_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 name

• schema (object, required) - JSON schema definition

• description (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 UUID

• rows (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 UUID

• filters (object, optional) - Query filters

• limit (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 UUID

• filters (object, required) - Row selection filters

• updates (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 UUID

• filters (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 name

• file_data (string, required) - Base64-encoded file data

• content_type (string, optional) - MIME type

• metadata (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 UUID

• expiry_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 identifier

• event_data (object, required) - Event payload

• metadata (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 type

• start_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 to

• filters (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 type

• start_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 name

• description (string, optional) - Project description

• settings (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 UUID

• project_name (string, optional) - New project name

• description (string, optional) - New description

• settings (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 delete

• confirm (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 UUID

• start_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 UUID

• features (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 identifier

• user_input (string, required) - User's input

• agent_response (string, required) - Agent's response

• feedback_score (number, optional) - User rating 1-5

• metadata (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 identifier

• session_id (string, required) - Session identifier

• feedback_type (string, required) - "positive" or "negative"

• feedback_text (string, optional) - Detailed feedback

• metrics (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 identifier

• session_id (string, required) - Session identifier

• completed (boolean, required) - Workflow completion status

• duration_ms (number, optional) - Workflow duration

• feedback (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 identifier

• error_type (string, required) - Error category

• error_message (string, required) - Error description

• context (object, optional) - Error context

• user_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 session

• start_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 identifier

• collection_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 identifier

• limit (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 type

• event_data (object, required) - Event payload

• target_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 user

• limit (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 UUID

• start_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 execute

• params (array[string], optional) - Query parameters for prepared statements

• read_only (boolean, optional) - Enforce read-only mode (SELECT only), default: false

• timeout_seconds (number, optional) - Query timeout in seconds, default: 30

• max_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: true

• include_constraints (boolean, optional) - Include constraint information, default: true

• include_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 create

• columns (array, required) - Column definitions

  • name (string, required) - Column name

  • type (string, required) - Column type (e.g., "VARCHAR(255)", "INTEGER", "TIMESTAMP")

  • nullable (boolean, optional) - Allow NULL values, default: true

  • primary_key (boolean, optional) - Is primary key, default: false

  • unique (boolean, optional) - Unique constraint, default: false

  • default (string, optional) - Default value

• indexes (array, optional) - Index definitions

  • name (string, optional) - Index name (auto-generated if not provided)

  • columns (array[string], required) - Columns to index

  • unique (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: 7

• compression (boolean, optional) - Compress backup, default: true

• include_schema (boolean, optional) - Include schema definition, default: true

• include_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 from

• restore_type (string, optional) - "full", "schema_only", or "data_only", default: "full"

• target_database (string, optional) - Restore to different database name

• confirm_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: true to 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: true

• include_queries (boolean, optional) - Include query performance stats, default: true

• include_storage (boolean, optional) - Include storage statistics, default: true

• include_replication (boolean, optional) - Include replication stats, default: false

• time_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"
}

Knowledge Graph Operations

Entity/relationship graph on top of your ZeroDB memories — create entities, link them, walk the graph, and run hybrid vector+graph search. Requires a core backend version that includes the graph_* MCP operations (AINative-Studio/core#8341); an older backend returns an "operation not recognized" error for these four tools.

zerodb_graph_upsert_entity

Create or update a knowledge graph entity. If an entity with the same canonical_name + entity_type already exists, its aliases are merged and memory_count is incremented instead of creating a duplicate.

Parameters:

• canonical_name (string, required) - Entity canonical name

• entity_type (string, required) - Entity type, e.g. person, org, tech, concept

• aliases (array[string], optional) - Known aliases for the entity

• properties (object, optional) - Arbitrary entity properties

• project_id (string, optional) - When provided, entity_type is checked against that project's ontology; a warning (not a block) is returned if it is not in the allowed list

Returns:

{
  "id": "ent_abc123",
  "canonical_name": "Alice Johnson",
  "entity_type": "person",
  "aliases": ["Alice"],
  "properties": { "role": "engineer" },
  "memory_count": 1,
  "status": "created"
}

zerodb_graph_create_edge

Create or strengthen a directed edge (relationship) between two entities that already exist in the graph. Does not create the entities — use zerodb_graph_upsert_entity first.

Parameters:

• source_name (string, required) - Source entity canonical name (must already exist)

• target_name (string, required) - Target entity canonical name (must already exist)

• predicate (string, required) - Relationship type, e.g. works_at, located_in, depends_on

• confidence (number, optional) - Edge confidence 0.0-1.0, default: 0.8

• properties (object, optional) - Arbitrary edge properties

Example:

{
  "source_name": "Alice Johnson",
  "target_name": "Acme Corp",
  "predicate": "works_at",
  "confidence": 0.9
}

zerodb_graph_traverse

Multi-hop traversal of the knowledge graph starting from an entity. Returns nodes, edges, and paths discovered within max_hops.

Parameters:

• entity (string, required) - Entity name or ID to start traversal from

• max_hops (number, optional) - Maximum traversal depth (1-5), default: 3

• predicates (array[string], optional) - Only follow edges with these predicate types

• min_confidence (number, optional) - Minimum edge confidence to follow, default: 0.0

• as_of (string, optional) - ISO timestamp — only return edges valid at this point in time

Example:

{
  "entity": "Alice Johnson",
  "max_hops": 2
}

zerodb_graph_rag_search

GraphRAG hybrid search — blends vector similarity with knowledge graph proximity. graph_weight=0.0 behaves like pure vector search; graph_weight=1.0 is pure graph proximity ranking; the default 0.3 blends both.

Parameters:

• query (string, required) - Search query text

• limit (number, optional) - Maximum results to return, default: 10

• graph_weight (number, optional) - Blend factor: 0=pure vector, 1=pure graph proximity, default: 0.3

• max_hops (number, optional) - Maximum graph traversal depth for the graph-proximity component, default: 2

Example:

{
  "query": "pricing strategy",
  "limit": 5,
  "graph_weight": 0.5
}

zerodb_graph_list_entities

List knowledge graph entities for the current user, optionally filtered by entity type, paginated by memory_count descending.

Parameters:

• entity_type (string, optional) - Filter by entity type, e.g. person, org, tech, concept

• limit (number, optional) - Max results, default: 50

• offset (number, optional) - Pagination offset, default: 0

zerodb_graph_neighbors

Get the direct (1-hop) neighbors of an entity, with relationship and entity metadata. Bounded to a single hop — use zerodb_graph_traverse for a deeper walk.

Parameters:

• entity_name (string, required) - Entity name to find neighbors of (must already exist)

• limit (number, optional) - Max neighbors to return, default: 50

zerodb_graph_stats

Graph analytics for the current user: node count, edge count, density, entity-type and predicate distributions, and top entities by connectivity. No parameters.

zerodb_graph_merge_entities

Merge duplicate entities into a canonical entity, moving all edges and aliases from the merge targets and deleting the duplicates. Destructive — cannot be undone.

Parameters:

• canonical (string, required) - Canonical entity name to keep

• merge (array[string], required) - Entity names to merge into the canonical entity and delete

zerodb_graph_ontology_get

Get the ontology (allowed entity types, predicates per type, constraints) for a project. Returns a not-found error if no ontology is defined yet.

Parameters:

• project_id (string, required) - Project UUID

zerodb_graph_ontology_upsert

Create or update a project's ontology. Version is auto-incremented on update.

Parameters:

• project_id (string, required) - Project UUID

• entity_types (array[string], required) - Allowed entity types for this project

• predicates (object, optional) - Allowed predicates per entity type, e.g. {"customer": {"places": "order"}}

• constraints (object, optional) - Optional additional constraints

zerodb_graph_ontology_infer

Infer a candidate ontology from existing graph data by analyzing entity-type and predicate frequency. When project_id is given, also returns a diff against that project's current ontology.

Parameters:

• min_entity_count (number, optional) - Minimum entity-type occurrences to suggest it, default: 3

• min_predicate_count (number, optional) - Minimum predicate occurrences to suggest it, default: 2

• project_id (string, optional) - Project UUID to diff against

zerodb_graph_ontology_suggestions

Human-readable, actionable suggestions for improving a project's ontology (reclassify generic-typed entities, missing predicates, undeclared entity types).

Parameters:

• project_id (string, optional) - Project UUID to scope suggestions to

zerodb_graph_contradictions_list

List contradictions: edges superseded because a newer edge contradicted an existing relationship on the same (source, predicate) pair.

Parameters:

• limit (number, optional) - Max contradictions to return, default: 50

zerodb_graph_contradictions_resolve

Resolve a contradiction on a superseded edge found via zerodb_graph_contradictions_list.

Parameters:

• edge_id (string, required) - UUID of the superseded (old) edge to resolve

• action (string, required) - One of accept_new (no-op, keeps current state), keep_both (restores the old edge), reject_new (deletes the new edge and restores the old one)

zerodb_graph_centrality

Entities ranked by degree centrality (total/in/out degree, hub score, critical-node flag). Requires the graph.compute_centrality background task to have run at least once — returns an empty list otherwise.

Parameters:

• entity_type (string, optional) - Filter by entity type

• limit (number, optional) - Max entities to return, default: 50

• critical_only (boolean, optional) - Only return entities flagged as critical infrastructure nodes, default: false

zerodb_graph_export

Export the knowledge graph as JSON (nodes + edges, D3/Cytoscape-compatible). For GEXF (Gephi), use the underlying HTTP export route directly.

Parameters:

• entity_type (string, optional) - Filter by entity type

• limit (number, optional) - Max entities to export, default: 5000

• min_confidence (number, optional) - Minimum edge confidence to include, default: 0.0

Configuration

Environment Variables

All configuration is done through environment variables. Set these in your MCP server configuration.

* Either ZERODB_API_KEY or both ZERODB_USERNAME and ZERODB_PASSWORD must be provided.

Authentication

The MCP server supports two authentication methods:

API Key (Recommended)

Set ZERODB_API_KEY in your environment. The API key is used as a static Bearer token for all requests -- no login flow, no token renewal needed.

Username/Password (Legacy)

Set ZERODB_USERNAME and ZERODB_PASSWORD. The server authenticates on startup, stores the JWT in memory, and automatically renews it every 25 minutes (tokens expire after 30 minutes). Use zerodb_renew_token to manually renew if needed.

Backward compatibility: If you have ZERODB_USERNAME/ZERODB_PASSWORD configured, it will continue to work. We recommend migrating to API key auth for simplicity and security.

Security Best Practices

1. Use API keys instead of passwords: API keys don't require plaintext password storage

2. Store credentials securely: Use environment variables, never hardcode

3. Use project-specific credentials: Create separate projects for different applications

4. Rotate API keys regularly: Regenerate keys every 90 days

5. Monitor API usage: Check for unusual activity in project stats

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 Password Auth to API Key Auth

Password auth (ZERODB_USERNAME/ZERODB_PASSWORD) is deprecated and will be removed in v3.0. The server will print a deprecation warning on startup if password auth is detected.

Step 1: Get Your API Key

1. Go to https://ainative.studio/settings

2. Navigate to the API Keys section

3. Click Create API Key

4. Copy the key (it starts with zdb_)

Step 2: Update Your Configuration

Old config (deprecated):

{
  "mcpServers": {
    "zerodb": {
      "command": "npx",
      "args": ["ainative-zerodb-mcp-server"],
      "env": {
        "ZERODB_API_URL": "https://api.ainative.studio",
        "ZERODB_PROJECT_ID": "your-project-id",
        "ZERODB_USERNAME": "your-email@example.com",
        "ZERODB_PASSWORD": "YourPassword123!"
      }
    }
  }
}

New config (recommended):

{
  "mcpServers": {
    "zerodb": {
      "command": "npx",
      "args": ["ainative-zerodb-mcp-server"],
      "env": {
        "ZERODB_API_URL": "https://api.ainative.studio",
        "ZERODB_PROJECT_ID": "your-project-id",
        "ZERODB_API_KEY": "zdb_your-api-key-here"
      }
    }
  }
}

Why Switch?

• No plaintext passwords — API keys don't require storing your account password

• No token renewal — API keys are used directly as Bearer tokens, no login/refresh flow

• Revocable — Rotate or revoke individual keys without changing your password

• Scoped — Future support for project-scoped and read-only keys

Migrating from v1.x to v2.0.0

Breaking Changes

1. 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

2. 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

3. 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" }
   }

4. New Required Environment Variables

   • ZERODB_PROJECT_ID is now required (was optional in v1.x)

   Migration: Add to your config:

   {
     "env": {
       "ZERODB_PROJECT_ID": "your-project-id"
     }
   }

New Features Available

1. 54 New Operations - Full API coverage beyond memory and vector operations

2. Quantum Compression - Reduce vector storage by up to 50%

3. NoSQL Tables - Structured data storage and queries

4. File Management - Upload and manage files

5. Event System - Event-driven architecture support

6. RLHF Collection - Built-in feedback collection for model training

7. Admin Tools - System monitoring and optimization

Migration Steps

1. Update Package

   npm update ainative-zerodb-mcp-server
   # or
   npm install -g ainative-zerodb-mcp-server@2.0.0

2. Update Configuration

   • Add ZERODB_PROJECT_ID to environment variables

   • Update any custom tool names to include zerodb_ prefix

3. Test Existing Functionality

   • All v1.x operations remain compatible

   • Test memory and vector operations still work

4. 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:

• If using API key: verify ZERODB_API_KEY is correct and not expired

• If using username/password: verify ZERODB_USERNAME and ZERODB_PASSWORD are correct

• Check that your account is active

• Try manual token renewal: zerodb_renew_token (username/password auth only)

2. Project Not Found

Error: Project not found: [project-id]

Solutions:

• Verify ZERODB_PROJECT_ID is 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

1. Documentation: https://docs.ainative.studio/zerodb

2. GitHub Issues: https://github.com/AINative-Studio/ainative-zerodb-mcp-server/issues

3. Email Support: support@ainative.studio

4. 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_ID environment 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