Overview

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 Service Key (bypasses RLS - admin use) Client Key (respects RLS - user-level)

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 Claude CLI Copy Config

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

Create a Client Key

Generate a client key with appropriate scopes:

fluxbase clientkeys create --name "My IDE" \
  --scopes "read:tables,write:tables,execute:functions,read:storage"

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}'

Production Warning

Service keys grant full database access. Never expose them in client-side code or public repositories.

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}'

When to use Client Keys

Use client keys when you need RLS enforcement, such as in multi-tenant applications or when the AI assistant should only access user-specific data.

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:

1. The client discovers endpoints via /.well-known/oauth-authorization-server
2. It registers itself via POST /mcp/oauth/register (no pre-configured credentials needed)
3. The user is prompted to log in to Fluxbase
4. 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