MCP Vector Sync

MCP service for automatic synchronization of multi-tenant search vectors with Supabase using a 100% event-based system.

Description

This service receives real-time notifications from Supabase when there are changes to the proyectos table, generates vector embeddings using OpenAI, and updates the proyecto_vector table while maintaining efficient vector lookup for each tenant. It implements the Model Context Protocol (MCP) to expose synchronization tools and resources.

Characteristics

• 100% event-based system (direct webhooks from Supabase)

• Generating embeddings with OpenAI

• Immediate processing of project changes

• Automatic retry system with exponential backoff

• Audit log for debugging and monitoring

• Multi-tenant synchronization with complete data isolation

• Exhibition of MCP tools for control and monitoring

• Health check server for monitoring

• Containerized with Docker for easy deployment

• Compatible with Railway for production deployment

Event architecture

The system uses a completely event-driven architecture:

1. Trigger in Supabase : When a project is created or modified, a trigger sends a webhook directly to the service

2. Controlled delay processing : For new inserts, a 20-second delay is applied to avoid race conditions.

3. Automatic retries : In case of failures, the system retries up to 3 times with exponential backoff (2, 4, 8 seconds)

4. Audit Log : All attempts are logged to the webhook_logs table for debugging and monitoring.

Requirements

• Node.js >= 18

• Supabase with proyectos table and proyecto_vector

• OpenAI API Key

• Docker (for deployment)

Configuration

The service uses environment variables for its configuration:

Local Development

1. Install dependencies:

2. Configure environment variables (create .env file in the project root)

3. Run in development mode:

Docker

To run the service with Docker:

Or with Docker Compose:

Deployment on Railway

Preparation

1. Create a repository on GitHub and upload the code:

2. Create a Railway account if you don't have one yet.

Deployment

1. In Railway, create a new project from GitHub

2. Select the mcp-vector-sync repository

3. Railway will automatically detect the Dockerfile

4. Configure environment variables in the "Variables" section

5. Deploy the service

Railway will use the railway.json file to configure the deployment and the Dockerfile to build the image.

Monitoring

Once deployed, you can monitor the service using the /health endpoint:

Webhook Endpoint

The system receives webhooks on the following endpoint:

The expected payload for the webhook must include:

MCP Tools

The service exposes the following MCP tools:

• sync-tenant : Forces synchronization for a specific tenant

• get-sync-status : Gets the synchronization status of a tenant

• control-monitor : Starts or stops the synchronization monitor

Troubleshooting

• If there are errors with the embedding generation, check your OpenAI API key.

• For connection issues with Supabase, make sure the URL and service key are correct.

• Review the logs in webhook_logs to diagnose webhook issues.

• Detailed logs can be enabled with LOG_LEVEL=debug

Maintenance

To update the service:

1. Make changes to the code

2. Update the version in package.json

3. Commit and push to GitHub

4. Railway will detect changes and automatically redeploy

Safety Considerations

• Never include credentials or API keys in your source code.

• Use environment variables for all sensitive settings

• Make sure the Supabase service role key has only the necessary permissions

• In production environments, consider implementing authentication for webhooks.

• Configure rate limiting to protect against DoS attacks