Overview

Name: Fluxbase
Author: Fluxbase

Fluxbase includes a built-in MCP (Model Context Protocol) server that enables AI assistants like Claude to interact with your database, storage, functions, and jobs.

Quick Setup

Configure your MCP client to connect with your Fluxbase instance.

Fluxbase URL

Authentication

API Key (optional)

Service Key bypasses Row Level Security and has full database access. Use Client Key for user-level access that respects RLS policies.

Tip: Enter your API key above for one-click setup, or leave it empty to be prompted in your IDE.

Add to VS Code Add to VS Code Insiders

View configuration JSON

Manual Configuration

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "fluxbase": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "X-Service-Key": "your-service-key"
      }
    }
  }
}

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

VS Code with Claude Extension

Add to your VS Code settings (settings.json) or use the "Add to VS Code" button above:

{
  "claude.mcpServers": {
    "fluxbase": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "X-Service-Key": "your-service-key"
      }
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings → Features → MCP Servers):

{
  "fluxbase": {
    "type": "http",
    "url": "http://localhost:8080/mcp",
    "headers": {
      "X-Service-Key": "your-service-key"
    }
  }
}

Claude Code CLI

claude mcp add --transport http fluxbase http://localhost:8080/mcp \
  --header "X-Service-Key: your-service-key"

Other MCP Clients

Any MCP-compatible client can connect using:

URL: http://your-server:8080/mcp
Type: http
Auth Header: X-Service-Key: your-key or X-Client-Key: your-key
Protocol: JSON-RPC 2.0 over HTTP POST

Overview

The MCP server exposes Fluxbase functionality through a standardized JSON-RPC 2.0 protocol, allowing AI assistants to:

Query and modify database tables (with Row Level Security)
Upload, download, and manage storage files
Invoke edge functions and RPC procedures
Submit and monitor background jobs
Search vector embeddings for RAG applications

Configuration

Enable the MCP server in your fluxbase.yaml:

mcp:
  enabled: true
  base_path: /mcp
  session_timeout: 3600s
  max_message_size: 10485760 # 10MB
  rate_limit_per_min: 100
  allowed_tools: [] # Empty = all tools enabled
  allowed_resources: [] # Empty = all resources enabled

Configuration Options

| Option | Default | Description | | -------------------- | ---------- | ------------------------------- | | enabled | false | Enable the MCP server endpoint | | base_path | /mcp | URL path for MCP endpoints | | session_timeout | 3600s | Session timeout for connections | | max_message_size | 10485760 | Maximum request size in bytes | | rate_limit_per_min | 100 | Requests per minute per client | | allowed_tools | [] | Whitelist of allowed tools | | allowed_resources | [] | Whitelist of allowed resources |

Authentication

The MCP server requires authentication for all requests. Supported methods:

Service Keys (Admin Access)

Service keys bypass Row Level Security (RLS) and have full database access. Recommended for:

Administrative automation
CI/CD pipelines
Development and testing
Backend service integration

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-service-key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Client Keys (User-Level Access)

Client keys respect Row Level Security - users only see data they're authorized to access. Create a client key with specific scopes:

fluxbase clientkeys create --name "AI Assistant" \
  --scopes "read:tables,write:tables,execute:functions"

Use the key in requests:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Client-Key: your-client-key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

OAuth 2.1 (Interactive Clients)

MCP clients like Claude Desktop can authenticate using OAuth 2.1 with Dynamic Client Registration (DCR). This provides user-scoped access that respects Row Level Security.

How it works:

The client discovers endpoints via /.well-known/oauth-authorization-server
It registers itself via POST /mcp/oauth/register (no pre-configured credentials needed)
The user is prompted to log in to Fluxbase
After authentication, the client receives tokens tied to that user

Configuration:

mcp:
  enabled: true
  oauth:
    enabled: true # Enable OAuth for MCP
    dcr_enabled: true # Enable Dynamic Client Registration
    token_expiry: 1h # Access token lifetime
    refresh_token_expiry: 168h # Refresh token lifetime (7 days)

Claude Desktop config (OAuth):

{
  "mcpServers": {
    "fluxbase": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude will automatically handle OAuth discovery and authentication.

Available Scopes

| Scope | Description | | ------------------- | ------------------------------ | | read:tables | Query database tables | | write:tables | Insert, update, delete records | | execute:functions | Invoke edge functions | | execute:rpc | Execute RPC procedures | | read:storage | List and download files | | write:storage | Upload and delete files | | execute:jobs | Submit and monitor jobs | | read:vectors | Vector similarity search | | read:schema | Access database schema |

Endpoints

| Endpoint | Method | Description | | ----------------------------------------- | ------ | --------------------------------- | | /mcp/health | GET | Health check (no auth required) | | /mcp | POST | JSON-RPC requests | | /.well-known/oauth-authorization-server | GET | OAuth server metadata (discovery) | | /.well-known/oauth-protected-resource | GET | Protected resource metadata | | /mcp/oauth/register | POST | Dynamic Client Registration | | /mcp/oauth/authorize | GET | OAuth authorization endpoint | | /mcp/oauth/token | POST | Token exchange endpoint | | /mcp/oauth/revoke | POST | Token revocation |

Protocol

The MCP server implements JSON-RPC 2.0 with the following methods:

initialize - Protocol handshake
ping - Health check
tools/list - List available tools
tools/call - Execute a tool
resources/list - List available resources
resources/read - Read a resource

Example Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "query_table",
    "arguments": {
      "table": "users",
      "select": "id,email,created_at",
      "filter": { "is_active": "eq.true" },
      "limit": 10
    }
  },
  "id": 1
}

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\":\"...\",\"email\":\"user@example.com\",\"created_at\":\"...\"}]"
      }
    ],
    "isError": false
  },
  "id": 1
}

Security

All database operations respect Row Level Security (RLS) policies when using Client Keys or OAuth
Service keys bypass RLS for administrative operations
Internal schemas (auth, storage, functions, jobs) are hidden from non-admins
SQL injection is prevented through parameterized queries and identifier validation
File downloads are limited to 10MB to prevent memory issues

Legacy Configuration (stdio transport)

If your MCP client only supports stdio transport (older clients), use the mcp-remote proxy:

{
  "mcpServers": {
    "fluxbase": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "--http",
        "http://localhost:8080/mcp",
        "--header",
        "X-Service-Key: your-service-key"
      ]
    }
  }
}

Next Steps

Available Tools - Complete tool reference
Available Resources - Resource reference
OAuth Authentication - OAuth 2.1 details
Security Best Practices - Security guidelines