Supabase MCP Adapter Service

This server implements the MCP specification to expose the functionality of a Supabase instance, facilitating orchestration across its core components: Postgres, File Storage, and Serverless Functions.

Core Capabilities Summary

The adapter functions as an intermediary layer, offering standardized access to:

• Relational Data Operations: Advanced querying, manipulation, and schema interaction within the underlying PostgreSQL database.
• Object Storage Control: Uploading, retrieving, and managing binary artifacts and user-uploaded assets.
• Serverless Logic Invocation: Triggering and receiving results from deployed Edge Functions.
• Administrative Functions: Managing project users, authentication states, and access control mechanisms.

System Blueprint

The implementation relies on a modular Node.js/TypeScript foundation to ensure maintainability and type safety:

supabase-adapter/ ├── src/ │ ├── main.ts # Entry point and MCP interface binding │ └── models/ │ └── types.ts # Data schemas and operational signatures ├── package.json ├── tsconfig.json ├── configuration.env.sample # Template for sensitive setup parameters └── server.config.json.example # Template for service runtime settings

Primary Modules

• Handler Class: The main class conforming to the MCP server contract, processing inbound requests.
• Type Contracts: Enforced TypeScript definitions ensuring input/output fidelity.
• Credential Management: Secure retrieval of connection strings and keys from the execution environment.
• Resilience Layer: Comprehensive exception handling for connectivity issues, authorization denials, and invalid payload arguments.

Prerequisites for Deployment

To initialize this service, you require:

• Runtime Environment: Node.js version 16.x or newer.
• Active Supabase Instance possessing:
  • The project's API Endpoint URL.
  • The Service Role Key (essential for privileged administrative actions).
  • A Management Access Token (for organizational or project setup actions).
• An MCP compliant client application capable of interfacing with this server.

Deployment Sequence

Automated Installation (via Smithery)

Integration into Claude Desktop environments via the Smithery utility:

bash npx -y @smithery/cli install supabase-adapter-mcp --client claude

Manual Setup Steps

1. Obtain the source code repository: bash git clone https://github.com/DynamicEndpoints/supabase-mcp.git cd supabase-mcp

2. Install required dependencies: bash npm install

3. Configure environment variables (copy template and populate): bash cp configuration.env.sample .env

Edit .env file:

SUPABASE_URL=https://your-project-ref.supabase.co SUPABASE_KEY=your_service_role_key SUPABASE_ACCESS_TOKEN=your_management_token

1. Generate executable JavaScript artifacts: bash npm run build

Runtime Configuration Details

The adapter's behavior is governed by settings defined in environment variables and the optional server.config.json file, offering granular control over networking and service boundaries.

Service Network Settings

{ "server": { "name": "supabase-adapter", "version": "1.0.0", "port": 4000, "host": "0.0.0.0" } }

Supabase Connectivity Parameters

{ "supabase": { "project": { "url": "{{SUPABASE_URL}}", "key": "{{SUPABASE_KEY}}", "accessToken": "{{SUPABASE_ACCESS_TOKEN}}" }, "storage": { "defaultBucket": "public_assets", "maxPayloadBytes": 52428800, "permittedMimeTypes": [ "image/jpeg", "application/pdf", "text/plain" ] }, "db_settings": { "connectionPoolSize": 10, "queryTimeoutMs": 45000, "enableSsl": true }, "auth_policy": { "autoConfirm": false, "signupEnabled": true, "jwtDefaults": { "expiry": "1h", "signatureAlgo": "HS256" } } } }

Operational Telemetry (Logging)

{ "logging": { "verbosity": "warn", "outputFormat": "text", "sinks": ["stdout", "file"], "fileConfig": { "location": "logs/adapter.log", "rotationSize": "20m", "maxFiles": 7 } } }

Inter-Service Security & Throttling

{ "security": { "corsPolicy": { "active": true, "allowedHosts": ["*"], "methodsAllowed": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"], "headersExposed": ["Content-Type", "Authorization", "X-Request-ID"] }, "rateLimiting": { "active": true, "timeframeMs": 600000, "maxRequests": 150 } } }

Health and Performance Monitoring

{ "monitoring": { "active": true, "metricsCapture": { "enabled": true, "frequencySec": 90 }, "livenessProbe": { "enabled": true, "endpoint": "/status" } } }

Refer to server.config.json.example for the comprehensive schema.

MCP Consumer Integration

To register this adapter within the main MCP orchestration context (cline_mcp_settings.json):

{ "mcpServers": { "supabase_adapter": { "command": "node", "args": ["path/to/supabase-adapter/build/main.js"], "env": { "SUPABASE_URL": "your_project_url", "SUPABASE_KEY": "your_service_role_key", "SUPABASE_ACCESS_TOKEN": "your_access_token" }, "configPath": "path/to/server.config.json" } } }

Toolset Reference

Database Interaction Suite

insert_row

Inserts a new data entity into the specified table; optionally returns specified output columns.

typescript { table: string; payload: Record; output_columns?: string[]; }

Example: typescript { table: "products", payload: { name: "Gadget X", price: 99.99 }, output_columns: ["id", "created_at"] }

query_entities

Retrieves multiple records, supporting complex relational filtering and projection.

typescript { table: string; projection?: string[]; criteria?: Record; joins?: Array<{ type: 'inner' | 'left'; target_table: string; join_condition: string; }>; }

Example: typescript { table: "orders", projection: ["id", "total", "customer.email"], criteria: { status: "pending" }, joins: [{ type: "left", target_table: "customers", join_condition: "orders.customer_id=customers.id" }] }

modify_row

Updates existing dataset entries based on provided criteria.

typescript { table: string; updates: Record; filter_criteria?: Record; returning_fields?: string[]; }

Example: typescript { table: "profiles", updates: { last_login: new Date().toISOString() }, filter_criteria: { user_uuid: "xyz-123" }, returning_fields: ["id", "last_login"] }

remove_entity

Permanently erases records matching the supplied conditions.

typescript { table: string; filter_criteria?: Record; returning_deleted_ids?: string[]; }

Example: typescript { table: "temp_data", filter_criteria: { is_stale: true } }

File System Operations (Storage)

put_object

Stores a new file or overwrites an existing one in a designated bucket.

typescript { bucket_name: string; object_path: string; file_data: File | Buffer; metadata?: { cache_control?: string; mime_type?: string; replace_if_exists?: boolean; }; }

Example: typescript { bucket_name: "media-uploads", object_path: "user_data/image_001.png", file_data: imageBuffer, metadata: { mime_type: "image/png" } }

get_object

Retrieves the binary content of a specific object from storage.

typescript { bucket_name: string; object_path: string; }

Example: typescript { bucket_name: "archives", object_path: "backup/db_export.sql" }

Serverless Runtime Execution

execute_function

Triggers a remote Edge Function, passing input arguments and specifying the desired response format.

typescript { function_name: string; payload_arguments?: Record; request_settings?: { http_headers?: Record; expected_output_format?: 'json' | 'text' | 'binary'; }; }

Example: typescript { function_name: "process-notification", payload_arguments: { user_id: 42, message: "New Alert" } }

Identity and Access Management (IAM)

fetch_all_users

Retrieves a paginated list of all registered system users.

typescript { page_index?: number; items_per_page?: number; }

provision_new_user

Creates a new authentication record, optionally setting initial user metadata.

typescript { user_email: string; user_pass: string; custom_metadata?: Record; }

modify_user_profile

Updates core or custom attributes for an existing user identity.

typescript { identity_id: string; new_email?: string; new_password?: string; metadata_patches?: Record; }

retire_user

Deactivates or permanently removes a user account.

typescript { identity_id: string; }

grant_user_permission

Associates a specific authorization role with a user entity.

typescript { identity_id: string; role_name: string; }

revoke_user_permission

Disassociates a security role from a user identity.

typescript { identity_id: string; role_name: string; }

Error Contract

Failures are standardized to simplify client-side error resolution, providing a consistent structure across network, database, or authorization exceptions:

typescript { error_code: StandardErrorCode; human_readable_message: string; internal_diagnostic?: any; }

Development Lifecycle

Executing Unit Tests

bash npm run check

Compilation Process

bash npm run compile

Code Quality Analysis

bash npm run lint-check

Evaluation Harness (MCP Evals)

To execute functional tests using the dedicated evaluation client, ensure environment variables are sourced before invoking:

bash API_KEY=secret_key npx mcp-eval ./tests/functional.mcp src/main.ts

Contribution Guidelines

1. Duplicate the repository to your own namespace.
2. Establish a dedicated feature branch for your modifications.
3. Commit precise, atomic changes.
4. Submit a Merge Request against the primary repository branch.

Licensing

This component is distributed under the permissive MIT License (see LICENSE file).

Support and Issue Resolution

For troubleshooting:

1. Search the existing issue tracker for prior resolutions.
2. If unresolved, submit a new issue detailing the context, steps to reproduce, and relevant system logs.

ISO CLOUD DEFINITION RECAP: Cloud computing fundamentally relies on NIST's five characteristics: self-service provisioning, broad accessibility, shared resource pooling, rapid scalability, and metered service delivery, all underpinning the efficiency of modern distributed systems.