risk-tiered sql query execution with safety classification
Executes PostgreSQL queries against Supabase databases with automatic risk classification into three tiers: Safe (SELECT-only, always allowed), Write (INSERT/UPDATE/DELETE, requires unsafe mode), and Destructive (DROP/CREATE, requires unsafe mode + explicit confirmation). The system parses incoming SQL, classifies operations by AST analysis, and enforces execution gates based on the current safety mode setting, preventing accidental schema destruction while enabling controlled data mutations.
Unique: Implements a three-tier safety classification system (Safe/Write/Destructive) with explicit confirmation gates for destructive operations, integrated directly into the MCP tool invocation layer rather than as a separate middleware. This allows LLM agents to understand safety constraints at tool-call time and request user confirmation before executing risky operations.
vs alternatives: Safer than raw Supabase client libraries for agentic use because it enforces safety gates at the MCP protocol boundary, preventing LLMs from executing destructive SQL without explicit human confirmation, whereas direct client libraries rely on application-level safeguards that agents can bypass.
automatic migration versioning with schema change tracking
Automatically versions and tracks database schema changes by capturing migration metadata (timestamp, operation type, SQL statement) whenever destructive or schema-modifying operations execute. The system maintains a migration history log that can be queried to understand schema evolution, rollback points, and audit trails of who changed what when. This integrates with Supabase's native migration system to ensure version consistency across environments.
Unique: Integrates migration versioning directly into the MCP tool execution layer, automatically capturing and storing migration metadata whenever schema changes occur, rather than requiring developers to manually create migration files. This creates an implicit audit trail of all schema changes made through the chat interface.
vs alternatives: More transparent than manual migration management because every schema change is automatically versioned and logged, whereas traditional Supabase workflows require developers to manually create and track migration files, which can be forgotten or inconsistently documented.
exception handling and error reporting with context preservation
Catches and handles exceptions from database operations, Management API calls, and Auth SDK invocations, preserving error context (stack trace, operation details, input parameters) and returning user-friendly error messages. The system distinguishes between recoverable errors (connection timeouts, rate limits) and fatal errors (authentication failures, invalid SQL), and provides actionable error messages that help developers understand what went wrong. This prevents cryptic error messages from reaching users and enables better debugging.
Unique: Implements custom exception handling that preserves error context (operation details, input parameters) while sanitizing sensitive information before returning to users. This enables detailed debugging without leaking credentials or internal system details.
vs alternatives: More helpful than raw exception messages because it provides context-specific guidance (e.g., 'Invalid credentials — check SUPABASE_SERVICE_ROLE_KEY environment variable'), whereas raw exceptions often lack actionable information.
docker containerization with environment variable injection
Provides Dockerfile and Docker Compose configuration for containerizing the MCP server, enabling deployment in Docker environments with environment variable injection for credentials. The system builds a Python 3.12 container with all dependencies, exposes the stdio interface for MCP clients, and supports environment variable configuration for different deployment scenarios. This enables easy deployment to cloud platforms (AWS, GCP, Azure) and local Docker environments without manual setup.
Unique: Provides production-ready Dockerfile and Docker Compose configuration that handles Python dependency installation, environment variable injection, and stdio interface exposure for MCP clients. This enables one-command deployment to container environments.
vs alternatives: More portable than manual installation because Docker ensures consistent environments across development, staging, and production, whereas manual installation can have environment-specific issues (Python version, dependency conflicts).
testing framework with mock supabase clients and integration tests
Provides a testing framework with mock Supabase clients (database, Management API, Auth SDK) for unit testing without real Supabase credentials, and integration tests that run against a real Supabase instance. The system uses pytest for test execution, fixtures for test setup/teardown, and parametrized tests for testing multiple scenarios. This enables developers to test MCP tools locally without requiring a Supabase account and to verify integration with real Supabase services in CI/CD pipelines.
Unique: Provides both unit tests with mock clients and integration tests with real Supabase instances, enabling developers to test locally without credentials and verify integration in CI/CD pipelines. This dual approach balances test speed (mocks) with confidence (integration tests).
vs alternatives: More comprehensive than manual testing because automated tests catch regressions and edge cases, whereas manual testing is error-prone and doesn't scale as the codebase grows.
supabase management api endpoint orchestration with risk assessment
Provides MCP tool bindings for all Supabase Management API endpoints (project management, database configuration, auth settings, etc.) with automatic risk assessment and safety controls. The system maps Management API operations to MCP tools, injects project references automatically, classifies each endpoint by risk level (read-only vs destructive), and enforces safety gates similar to SQL execution. This enables chat-driven management of Supabase project infrastructure without requiring manual API calls or authentication.
Unique: Automatically injects project references and applies the same three-tier safety classification system (Safe/Write/Destructive) to Management API endpoints as it does to SQL queries, creating a unified safety model across database and infrastructure operations. This prevents accidental project-level destructive operations (e.g., database resets) without explicit confirmation.
vs alternatives: More accessible than raw Management API clients because it abstracts authentication, project reference injection, and safety gates into MCP tools that LLMs can safely invoke, whereas direct API clients require manual authentication handling and provide no guardrails against destructive operations.
supabase auth admin sdk method invocation with user lifecycle management
Exposes Supabase Auth Admin SDK methods as MCP tools, enabling chat-driven user management operations including user creation, updates, deletion, authentication operations (magic links, password recovery), and MFA management. The system wraps Auth Admin SDK calls with proper error handling, validates input parameters, and integrates with the safety system to require confirmation for destructive user operations (deletion, password resets). This allows developers to manage authentication state and user accounts without leaving their IDE.
Unique: Wraps the Supabase Auth Admin SDK with MCP tool bindings and integrates user deletion/password reset operations into the safety system, requiring explicit confirmation before destructive auth operations. This prevents LLMs from accidentally deleting user accounts or forcing password resets without human approval.
vs alternatives: Safer than direct Auth Admin SDK usage in agentic contexts because it enforces confirmation gates for destructive user operations, whereas raw SDK clients allow agents to delete users or reset passwords without safeguards, risking data loss and user disruption.
structured log retrieval and filtering with multi-collection support
Provides MCP tools to query Supabase logs across multiple collections (postgres, api_gateway, auth, realtime, etc.) with filtering by time range, search text, and custom criteria. The system constructs log queries using Supabase's log API, handles pagination for large result sets, and returns structured log entries as JSON objects. This enables developers to troubleshoot issues, monitor application behavior, and analyze performance without leaving their IDE or switching to the Supabase dashboard.
Unique: Integrates Supabase's multi-collection log API into MCP tools with automatic pagination and structured result formatting, allowing LLM agents to query logs conversationally without understanding the underlying log API schema. This abstracts log collection names, filter syntax, and pagination logic into simple tool parameters.
vs alternatives: More accessible than raw log API clients because it provides high-level filtering and search without requiring knowledge of Supabase's log query syntax, whereas direct API clients require developers to construct complex filter objects and handle pagination manually.
+5 more capabilities