ZeroDB MCP Server

How to use

You interact with the MCP server through an MCP client by configuring a local or remote MCP connection that points to the server. The server provides tools to store and search agent memory, upload and manage files, execute vector operations, query NoSQL tables, run PostgreSQL queries, and perform enterprise tasks like project management and RLHF data collection. Use the client to invoke tools such as zerodb_store_memory, zerodb_search_vectors, zerodb_store_vector, zerodb_create_table, zerodb_postgres_query, zerodb_rlhf_start, zerodb_admin_health, and many more. Your applications authenticate with a JWT-based flow, refresh tokens automatically, and you can renew tokens manually if needed.

How to install

# Prerequisites
# - Node.js >= 18.0.0
# - npm >= 9.0.0

# Global installation (preferred for quick start)
npm install -g ainative-zerodb-mcp-server

# Or run directly without installation
npx ainative-zerodb-mcp-server

Configuration

Configure the MCP connection to point to your ZeroDB project and credentials. The server expects environment variables for API access and project context. In your client configuration, provide the project ID, user credentials, and API URL you use to access ZeroDB.

{
  "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": "[email protected]",
        "ZERODB_PASSWORD": "YourPassword123!",
        "MCP_CONTEXT_WINDOW": "8192",
        "MCP_RETENTION_DAYS": "30"
      }
    }
  }
}

Security and access

The MCP server uses JWT authentication with automatic token renewal. Tokens are renewed on a schedule and can be renewed manually if needed. Protect credentials by keeping environment variables secure and using project-scoped access where possible. Rotate passwords periodically and monitor usage via project statistics.

Examples

Here are practical usage scenarios you can adapt in your client code. Store a memory entry for persistent context, search memories semantically, manage vectors for a knowledge base, and perform SQL-backed queries against PostgreSQL.

Troubleshooting

Common issues include authentication failures, misconfigured project IDs, vector dimension mismatches, expired tokens, and rate limits. Ensure credentials are correct, the project ID is set, vectors use the required 1536 dimensions, tokens renew automatically, and batch requests where possible to avoid rate limits.

Notes

This MCP server ships with a comprehensive test suite and security features. Leverage the admin tools to monitor health, review usage, and optimize performance. When upgrading, verify that your environment variables and project contexts remain consistent to avoid interruptions.

Migration and upgrade notes

When upgrading from earlier versions, you will typically provide the same project context and credentials, as well as any new options introduced by the upgrade. Validate token renewal behavior and ensure all tools you rely on maintain backward compatibility.

zerodb_store_memory

Store agent memory in ZeroDB for persistent context across sessions.

zerodb_search_memory

Search agent memory using semantic similarity.

zerodb_get_context

Get agent context window for the current session, optimized for token limits.

zerodb_store_vector

Store a 1536-dimensional vector embedding with metadata.

zerodb_batch_upsert_vectors

Batch upsert multiple vectors for improved performance.

zerodb_search_vectors

Search vectors by semantic similarity.

zerodb_delete_vector

Delete a specific vector by its ID.

zerodb_get_vector

Retrieve a specific vector by its ID.

zerodb_list_vectors

List vectors with pagination and filtering.

zerodb_vector_stats

Get statistics about vector storage.

zerodb_create_vector_index

Create a vector search index for improved performance.

zerodb_optimize_vectors

Optimize vector storage and indexes.

zerodb_export_vectors

Export vectors to an external format.

zerodb_quantum_compress

Compress a vector using quantum algorithms.

zerodb_quantum_decompress

Decompress quantum-compressed vector data.

zerodb_quantum_hybrid_search

Perform hybrid search using quantum-enhanced similarity.

zerodb_quantum_optimize

Optimize vector space with quantum techniques.

zerodb_quantum_feature_map

Generate a quantum feature map for a vector.

zerodb_quantum_kernel

Compute quantum kernel similarity between vectors.

zerodb_create_table

Create a new NoSQL table with schema.

zerodb_list_tables

List all NoSQL tables in the project.

zerodb_get_table

Get details of a NoSQL table.

zerodb_delete_table

Delete a NoSQL table and its data.

zerodb_insert_rows

Insert rows into a NoSQL table.

zerodb_query_rows

Query rows in a NoSQL table with filters.

zerodb_update_rows

Update rows in a NoSQL table.

zerodb_delete_rows

Delete rows from a NoSQL table.

zerodb_upload_file

Upload a file to ZeroDB storage.

zerodb_download_file

Download a file from ZeroDB storage.

zerodb_list_files

List files stored in ZeroDB.

zerodb_delete_file

Delete a file from storage.

zerodb_get_file_metadata

Get file metadata without downloading.

zerodb_generate_presigned_url

Generate a temporary presigned download URL for a file.

zerodb_create_event

Create a new event in the event system.

zerodb_list_events

List events with filtering and pagination.

zerodb_get_event

Get a specific event by ID.

zerodb_subscribe_events

Subscribe to an event stream over WebSocket.

zerodb_event_stats

Get event statistics and analytics.

zerodb_create_project

Create a new ZeroDB project.

zerodb_get_project

Get details of a project.

zerodb_list_projects

List all accessible projects.

zerodb_update_project

Update project settings.

zerodb_delete_project

Delete a project and its data.

zerodb_get_project_stats

Get project usage statistics.

zerodb_enable_database

Enable database features for a project.

zerodb_rlhf_interaction

Collect user interaction data for RLHF training.

zerodb_rlhf_agent_feedback

Collect agent performance feedback.

zerodb_rlhf_workflow

Collect RLHF workflow feedback.

zerodb_rlhf_error

Collect error reports for model improvement.

zerodb_rlhf_status

Get RLHF collection status.

zerodb_rlhf_summary

Get RLHF analytics summary.

zerodb_rlhf_start

Start RLHF data collection for a session.

zerodb_rlhf_stop

Stop RLHF data collection for a session.

zerodb_rlhf_session

Get all RLHF interactions for a session.

zerodb_rlhf_broadcast

Broadcast RLHF events to subscribers.

zerodb_admin_system_stats

Get system-wide statistics (admin).

zerodb_admin_list_projects

List all projects in the system (admin).

zerodb_admin_user_usage

Get user usage statistics (admin).

zerodb_admin_health

Get system health status (admin).

zerodb_admin_optimize

Optimize database and storage (admin).

zerodb_postgres_query

Execute SQL queries on the provisioned PostgreSQL instance.

zerodb_postgres_schema_info

Get detailed PostgreSQL schema information.

zerodb_postgres_create_table

Create a new PostgreSQL table with complete schema.

zerodb_postgres_backup

Trigger a PostgreSQL backup job.

zerodb_postgres_restore

Restore PostgreSQL from a backup.

zerodb_postgres_stats

Get PostgreSQL database statistics.