Frequently Asked Questions about MCP Server for UBOS

Q: What is the MCP Server?

A: The MCP Server (Model Context Protocol Server) is a service designed to streamline multi-tenant vector synchronization with Supabase using an event-driven architecture. It facilitates efficient data handling for AI applications by generating embeddings with OpenAI and providing real-time updates.

Q: How does the MCP Server work?

A: The MCP Server listens for real-time notifications from Supabase when changes occur in the proyectos table. Upon receiving a notification, it generates vector embeddings using OpenAI and updates the proyecto_vector table, ensuring efficient vector search capabilities for each tenant.

Q: What are the main features of the MCP Server?

A: Key features include a 100% event-driven architecture, OpenAI embeddings generation, immediate processing of project changes, automatic retry mechanism with exponential backoff, comprehensive audit logging, multi-tenant synchronization, MCP tooling exposure, a health check server, Docker containerization, and compatibility with Railway for deployment.

Q: What are the prerequisites for using the MCP Server?

A: You need Node.js >= 18, a Supabase instance with proyectos and proyecto_vector tables, an OpenAI API key, and Docker for deployment. Configuration is done via environment variables.

Q: How do I configure the MCP Server?

A: Configuration is managed through environment variables, including Supabase URL and service role key, OpenAI API key and model, rate limiting parameters, and logging level. These variables are set in a .env file or through your deployment platform.

Q: Can I run the MCP Server locally?

A: Yes, you can run the MCP Server locally by installing dependencies with npm install, configuring environment variables in a .env file, and running npm run dev.

Q: How do I deploy the MCP Server with Docker?

A: To deploy with Docker, build the image using docker build -t mcp-vector-sync . and run the container with docker run -p 3000:3000 --env-file .env mcp-vector-sync. Alternatively, use Docker Compose with docker-compose up.

Q: How do I deploy the MCP Server on Railway?

A: Create a GitHub repository, upload your code, create a Railway account, create a new project from the GitHub repository, and configure the necessary environment variables in the Railway dashboard.

Q: How can I monitor the MCP Server after deployment?

A: You can monitor the service using the /health endpoint, which provides the health status of the server. For example: https://tu-proyecto.railway.app/health.

Q: What is the webhook endpoint for the MCP Server?

A: The webhook endpoint is https://tu-proyecto.railway.app/webhook/project-update. It expects a JSON payload with inmobiliaria_id, project_id, event (INSERT or UPDATE), and timestamp.

Q: What MCP tools are exposed by the server?

A: The service exposes tools like sync-tenant to force synchronization for a specific tenant, get-sync-status to get the synchronization status of a tenant, and control-monitor to start or stop the synchronization monitor.

Q: What should I do if I encounter errors with embedding generation?

A: Verify that your OpenAI API key is correct and that it has the necessary permissions to generate embeddings.

Q: What should I do if I have connection issues with Supabase?

A: Ensure that the Supabase URL and service key are correct and that the service role key has the required permissions.

Q: How do I troubleshoot webhook issues?

A: Review the logs in the webhook_logs table to diagnose any problems with webhooks. Enable detailed logs with LOG_LEVEL=debug for more information.

Q: How do I update the MCP Server?

A: Make changes to the code, update the version in package.json, commit and push to GitHub, and Railway will automatically detect the changes and redeploy the service.

Q: What security considerations should I keep in mind?

A: Never include credentials or API keys in the source code. Use environment variables for all sensitive configuration. Ensure the Supabase service role key has only the necessary permissions. Consider implementing authentication for webhooks and configure rate limits to protect against DoS attacks.

Q: What is UBOS and how does the MCP Server relate to it?

A: UBOS is a full-stack AI Agent Development Platform. The MCP Server, available on the UBOS Asset Marketplace, helps streamline data synchronization, allowing developers to focus on building intelligent applications within the UBOS ecosystem.