🐳 Supabase MCP HTTP Stream Server for n8n

One-Click Docker deployment of Supabase MCP Server with native HTTP Stream Transport support for n8n, AI Agents, and modern automation workflows.

🚀 Quick Start

🌊 Coolify Deployment (Production)

For production deployment on Coolify, follow these detailed steps:

Step 1: Create Resource in Coolify

1. Navigate to your Coolify dashboard
2. Go to Projects → Select your project (e.g., "My first project")
3. Click "Add Resource" → "Docker Compose"
4. Choose "From GIT Repository" or "Raw Docker Compose"

Step 2: Configure Docker Compose

Option A: From GIT Repository

• Repository: https://github.com/BIFROTEK-com/supabase-mcp-http-stream-n8n.git
• Branch: main
• Docker Compose Location: docker/docker-compose.coolify.yaml

Option B: Raw Docker Compose Copy the content from docker/docker-compose.coolify.yaml

Step 3: Set Environment Variables

Configure these required environment variables in Coolify:

# 🔐 Required: Supabase Configuration
SUPABASE_ACCESS_TOKEN=sbp_your_access_token_here
SUPABASE_PROJECT_REF=your_project_ref_here

# 🔑 Security: API Keys (highly recommended)
MCP_API_KEYS=your-secure-api-key-here

# 📍 Domain Configuration
DOMAIN=your.domain.com

# ⚙️ Optional: Feature Configuration  
MCP_FEATURES=database,docs,development,functions
MCP_READ_ONLY=false
MCP_PORT=3333
NODE_ENV=production

# 🛡️ Optional: Security Settings
MCP_RATE_LIMIT_REQUESTS=100
MCP_RATE_LIMIT_GENERAL=60
MCP_ALLOWED_ORIGINS=*
NODE_LOG_LEVEL=warn

Step 4: Configure Domain & Traefik

1. Resource Name: supabase-mcp (or your preferred name)
2. Domain Configuration: https://your.domain.com:3333
   • ✅ Format: https://your-domain.com:3333
   • ✅ Port: Must be 3333 (the container port)
   • ✅ Protocol: Use https for SSL termination via Traefik

Step 5: Deploy

1. Save Configuration
2. Click "Deploy"
3. Monitor Logs for successful startup:

   ✅ MCP HTTP Server running on port 3333
   🚀 Streamable HTTP: POST /mcp
   🌊 SSE: GET/POST /sse
   ❤️ Health: GET /health
   🏠 Landing: GET /
   🔗 Ready for connections!
   

Step 6: Verify Deployment

Test your deployed instance using the API Examples below.

🐳 Local Development

1. Clone the repository:

git clone https://github.com/BIFROTEK-com/supabase-mcp-http-stream-n8n.git
cd supabase-mcp-http-stream-n8n

2. Create .env file:

cp env.example .env
# Edit .env with your Supabase credentials

3. Start the server:

cd docker && docker-compose up -d

4. Test the connection: See API Examples below

🔌 API Endpoints

🚀 HTTP Stream Transport (Recommended)

The modern MCP transport using HTTP streaming for real-time communication:

Endpoint	Method	Description
POST /mcp	POST	Main MCP API - HTTP Stream Transport
GET /health	GET	Health Check - Server status
GET /	GET	API Dashboard - Landing page (requires API key)
DELETE /mcp	DELETE	Session Termination - Terminate MCP session

Example Usage:

curl -X POST https://your-domain.com:3333/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

🌊 SSE Transport (n8n Compatible)

Server-Sent Events transport for legacy n8n MCP Client Tool Node compatibility:

Endpoint	Method	Description
GET /sse	GET	SSE Connection - Establish Server-Sent Events stream
POST /messages	POST	SSE Messages - Send JSON-RPC messages via SSE

SSE Features:

• ✅ Auto Session Management - Secure crypto-based session IDs
• ✅ Keep-Alive Pings - 15-second intervals for connection stability
• ✅ n8n Compatibility - Works with n8n MCP Client Tool Node
• ✅ Automatic Cleanup - Sessions auto-terminate on disconnect

SSE Connection Flow:

1. Connect: GET /sse establishes SSE stream
2. Receive: Server sends endpoint event with sessionId
3. Send Messages: POST /messages?sessionId=<session>
4. Keep-Alive: Server pings every 15 seconds
5. Disconnect: Automatic cleanup on connection close

Example Usage:

# 1. Establish SSE connection
curl -N -H "Accept: text/event-stream" https://your-domain.com:3333/sse

# Server responds:
# event: endpoint
# data: /messages?sessionId=abc123...
# data: {"type":"ready","status":"connected","session":"abc123..."}

# 2. Send messages via returned sessionId
curl -X POST https://your-domain.com:3333/messages?sessionId=abc123... \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

🛡️ Security Features

• ✅ API Key Authentication: Secure access control
• ✅ Rate Limiting: DoS protection (configurable)
• ✅ CORS Protection: Configurable origin restrictions
• ✅ Security Headers: Helmet.js with CSP
• ✅ Input Validation: JSON-RPC 2.0 validation
• ✅ SSL/TLS: HTTPS support via Traefik

📊 MCP Tools Available

Tool	Description
list_tables	Lists all database tables
list_extensions	Lists database extensions
execute_sql	Execute raw SQL queries
apply_migration	Apply database migrations
search_docs	Search Supabase documentation
list_edge_functions	List Edge Functions
deploy_edge_function	Deploy Edge Functions
get_project_url	Get project API URL
get_anon_key	Get anonymous API key
generate_typescript_types	Generate TypeScript types
list_migrations	List database migrations

🔧 Configuration

Environment Variables

Variable	Required	Default	Description
SUPABASE_ACCESS_TOKEN	✅	-	Supabase Management API token
SUPABASE_PROJECT_REF	✅	-	Your Supabase project reference
MCP_API_KEYS	⚠️	-	Comma-separated API keys
MCP_PORT	❌	3333	HTTP server port
MCP_FEATURES	❌	database,docs,development,functions	Enabled features
MCP_READ_ONLY	❌	false	Read-only mode
MCP_RATE_LIMIT_REQUESTS	❌	100	Requests per 15 minutes
MCP_RATE_LIMIT_GENERAL	❌	60	Requests per minute
MCP_ALLOWED_ORIGINS	❌	*	CORS allowed origins

Feature Groups

Enable specific features by setting MCP_FEATURES:

• database - Database operations (tables, SQL, migrations)
• docs - Supabase documentation search
• development - Development tools and utilities
• functions - Edge Functions management
• account - Account management (requires no project scoping)
• branching - Database branching operations
• storage - Storage management
• debug - Debugging tools

🔄 n8n Integration

⚠️ Important: Built-in MCP Node Issues

The built-in n8n MCP Client node has known issues with SSE Stream Transport (Deprecated) and may not work reliably with this server. For the best experience, we strongly recommend using the community-developed MCP Client node instead.

🌟 Recommended: Community MCP Node

Use the community node: @nerding-io/n8n-nodes-mcp

This community node provides:

• ✅ Full HTTP Stream Transport support (recommended)
• ✅ Reliable SSE Transport for legacy compatibility
• ✅ Better error handling and connection stability
• ✅ Active maintenance and community support
• ✅ AI Agent integration as a tool

📦 Installation

1. Install the community node in your n8n instance:

   # Via n8n UI: Settings → Community Nodes → Install
   # Package name: @nerding-io/n8n-nodes-mcp
   
   # Or via Docker environment:
   N8N_COMMUNITY_PACKAGES_ENABLED=true

2. Enable community nodes as tools (for AI Agents):

   # Required for using MCP Client as AI Agent tool
   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

🚀 Configuration with HTTP Stream Transport

Recommended Setup:

1. Create HTTP Streamable Credentials:

   • Base URL: https://your.domain.com:3333/mcp
   • API Key: Your configured API key
   • Transport: HTTP Streamable

2. Add MCP Client Node:

   • Connection Type: HTTP Streamable
   • Operation: List Tools / Execute Tool
   • Select your credentials

3. Example Tool Execution:

   {
     "tool": "list_tables",
     "parameters": {}
   }

🌊 Legacy SSE Configuration (if needed)

Only if HTTP Stream doesn't work:

1. Create SSE Credentials:

   • SSE URL: https://your.domain.com:3333/sse
   • Connection Type: Server-Sent Events (SSE)
   • Headers: X-API-Key: your-api-key

2. Configure Node:

   • Connection Type: Server-Sent Events (SSE)
   • Select your SSE credentials

Note: SSE is deprecated but maintained for compatibility. Always try HTTP Stream first.

🤖 AI Agent Integration

The community MCP node works perfectly as an AI Agent tool:

// Example AI Agent prompt
I need you to help me analyze my Supabase database. 
First, list all available tables using the list_tables tool.
Then, execute some SQL queries to get insights about the data.

Docker Configuration for AI Agents:

version: '3'
services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_COMMUNITY_PACKAGES_ENABLED=true
      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
      - MCP_API_KEY=your-supabase-mcp-api-key
    # ... rest of configuration

🎯 Use Cases

• Database Management: Query and manage Supabase databases
• AI Agents: Provide database access to AI assistants
• Automation: Integrate with n8n workflows
• Documentation: Search Supabase docs programmatically
• Edge Functions: Deploy and manage serverless functions
• Data Analysis: Execute complex SQL queries
• Schema Management: Handle database migrations

🔗 Related Projects

• MCP Framework - Model Context Protocol
• Supabase - Open source Firebase alternative
• n8n - Workflow automation platform
• Coolify - Self-hosted Heroku alternative

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🆘 Support

• GitHub Issues: Report bugs or request features
• Documentation: MCP Framework Docs
• Supabase: Official Documentation

---

Made with ❤️ by BIFROTEK