BaasixBaasix
Extend

MCP Server Integration

Baasix provides two ways to integrate with AI assistants via the Model Context Protocol (MCP):

TypeDescriptionBest For
Remote MCPBuilt-in HTTP endpoint at /mcpProduction deployments, remote servers, cloud environments
Local MCPStandalone @baasix/mcp npm packageLocal development, Claude Desktop, offline usage

Both provide the same 52 MCP tools for comprehensive Baasix operations.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect with external tools and data sources. With Baasix MCP, you can:

  • Create and manage database schemas using natural language
  • Perform CRUD operations on your data
  • Manage permissions and roles for your application
  • Query data with powerful filtering and aggregation
  • Handle authentication and user management
  • Upload and manage files

Features

CategoryToolsDescription
Schema Management13 toolsCreate, update, delete collections and relationships
Item Management5 toolsFull CRUD with 50+ filter operators
Authentication10 toolsLogin, register, magic links, invitations
Permissions9 toolsRole-based access control management
File Management3 toolsUpload, list, and manage files
Reports & Analytics2 toolsGenerate reports with grouping
Notifications3 toolsUser notification system
Realtime5 toolsWAL-based realtime management
Settings & Utils7 toolsApplication settings, templates, and utilities

The Remote MCP is built directly into the Baasix core server. It uses HTTP transport and is available at the /mcp endpoint when enabled.

Enable Remote MCP

Set the environment variable in your Baasix server:

MCP_ENABLED=true

The MCP endpoint will be available at http://your-server:port/mcp (configurable via MCP_PATH)

Authentication

Remote MCP supports multiple authentication methods (in priority order):

  1. Email/Password Headers:

    • X-MCP-Email: Your Baasix user email
    • X-MCP-Password: Your Baasix user password

  2. Query Parameters:

    • ?email=your@email.com&password=yourpassword appended to the MCP URL (not recommended for production)

  3. POST Body:

    • { "email": "your@email.com", "password": "yourpassword" } in the request body

  4. JWT Token:

    • Authorization: Bearer <your-jwt-token>

IDE Configuration

Claude Code / Anthropic CLI

Create a .mcp.json file in your project root:

Using query parameters (simplest):

{
  "mcpServers": {
    "baasix": {
      "type": "http",
      "url": "http://localhost:8056/mcp?email=admin@baasix.com&password=admin@123"
    }
  }
}

Or using headers:

{
  "mcpServers": {
    "baasix": {
      "type": "http",
      "url": "http://localhost:8056/mcp",
      "headers": {
        "X-MCP-Email": "admin@baasix.com",
        "X-MCP-Password": "admin@123"
      }
    }
  }
}

VS Code with GitHub Copilot

Create .vscode/mcp.json in your project:

{
  "servers": {
    "baasix": {
      "type": "http",
      "url": "http://localhost:8056/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mcpToken}",
        "X-MCP-Email": "${input:mcpEmail}",
        "X-MCP-Password": "${input:mcpPassword}"
      }
    }
  },
  "inputs": [
    {
      "id": "mcpToken",
      "type": "promptString",
      "description": "JWT Token (optional if using email/password)",
      "password": true
    },
    {
      "id": "mcpEmail",
      "type": "promptString",
      "description": "Baasix Email"
    },
    {
      "id": "mcpPassword",
      "type": "promptString",
      "description": "Baasix Password",
      "password": true
    }
  ]
}

Cursor IDE

Add to your Cursor settings:

{
  "mcpServers": {
    "baasix": {
      "type": "http",
      "url": "http://localhost:8056/mcp?email=admin@baasix.com&password=admin@123"
    }
  }
}

Local MCP

The Local MCP package runs as a standalone process on your machine. It uses stdio transport and connects to your Baasix server via HTTP internally.

Install

npm install @baasix/mcp

Environment Variables

VariableRequiredDefaultDescription
BAASIX_URLYeshttp://localhost:8056Baasix server URL
BAASIX_AUTH_TOKENNo*-Pre-obtained JWT token
BAASIX_EMAILNo*-Email for auto-authentication
BAASIX_PASSWORDNo*-Password for auto-authentication

*Either BAASIX_AUTH_TOKEN OR both BAASIX_EMAIL and BAASIX_PASSWORD must be provided.

IDE Configuration

Claude Code / Anthropic CLI

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "baasix": {
      "command": "npx",
      "args": ["@baasix/mcp"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "baasix": {
      "command": "npx",
      "args": ["@baasix/mcp"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

VS Code with GitHub Copilot

Create .vscode/mcp.json in your project:

{
  "servers": {
    "baasix": {
      "type": "stdio",
      "command": "npx",
      "args": ["@baasix/mcp"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Cursor IDE

{
  "mcpServers": {
    "baasix": {
      "command": "npx",
      "args": ["@baasix/mcp"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Comparison: Remote vs Local MCP

FeatureRemote MCPLocal MCP
TransportHTTP (Streamable HTTP)stdio
SetupEnable MCP_ENABLED=true on serverInstall @baasix/mcp package
AuthenticationHTTP headers, query params, or bodyEnvironment variables
Best ForCloud/remote servers, productionLocal development, Claude Desktop
ProcessRuns on Baasix serverRuns locally on your machine
LatencyDirect (no proxy)Additional HTTP hop
OfflineRequires server connectionCan connect to local server

Available Tools

Schema Management (13 tools)

ToolDescription
baasix_list_schemasList all collections with search/pagination
baasix_get_schemaGet detailed schema for a collection
baasix_create_schemaCreate a new collection schema
baasix_update_schemaUpdate existing schema
baasix_delete_schemaDelete a collection schema
baasix_add_indexAdd index to collection
baasix_remove_indexRemove index from collection
baasix_create_relationshipCreate M2O/O2M/M2M/M2A relationship
baasix_update_relationshipUpdate existing relationship
baasix_delete_relationshipDelete a relationship
baasix_export_schemasExport all schemas as JSON
baasix_import_schemasImport schemas from JSON

Item Management (5 tools)

ToolDescription
baasix_list_itemsQuery items with filters, sort, pagination
baasix_get_itemGet specific item by ID
baasix_create_itemCreate new item
baasix_update_itemUpdate existing item
baasix_delete_itemDelete item
baasix_sort_itemsReorder items in collection

Authentication (10 tools)

ToolDescription
baasix_auth_statusCheck authentication status
baasix_refresh_authRefresh authentication token
baasix_register_userRegister new user
baasix_loginLogin with email/password
baasix_logoutLogout current user
baasix_get_current_userGet current user info
baasix_send_inviteSend user invitation
baasix_verify_inviteVerify invitation token
baasix_send_magic_linkSend magic link/code
baasix_get_user_tenantsGet user's available tenants
baasix_switch_tenantSwitch tenant context

Permissions (9 tools)

ToolDescription
baasix_list_rolesList all roles
baasix_list_permissionsList all permissions
baasix_get_permissionGet permission by ID
baasix_get_permissionsGet permissions for a role
baasix_create_permissionCreate new permission
baasix_update_permissionUpdate permission
baasix_delete_permissionDelete permission
baasix_update_permissionsBulk update role permissions
baasix_reload_permissionsReload permission cache

File Management (3 tools)

ToolDescription
baasix_list_filesList files with metadata
baasix_get_file_infoGet file details
baasix_delete_fileDelete file

Reports & Analytics (2 tools)

ToolDescription
baasix_generate_reportGenerate reports with grouping
baasix_collection_statsGet collection statistics

Notifications (3 tools)

ToolDescription
baasix_list_notificationsList user notifications
baasix_send_notificationSend notification to users
baasix_mark_notification_seenMark notification as seen

Realtime (5 tools)

ToolDescription
baasix_realtime_statusGet realtime service status
baasix_realtime_configCheck PostgreSQL WAL configuration
baasix_realtime_collectionsList realtime-enabled collections
baasix_realtime_enableEnable realtime for a collection
baasix_realtime_disableDisable realtime for a collection

Settings & Templates (7 tools)

ToolDescription
baasix_get_settingsGet application settings
baasix_update_settingsUpdate settings
baasix_server_infoGet server health/info
baasix_list_templatesList email templates
baasix_get_templateGet email template by type
baasix_update_templateUpdate email template

Filter Operators

When using baasix_list_items, the filter parameter supports 50+ operators:

Comparison Operators

{"field": {"eq": "value"}}      // Equal
{"field": {"neq": "value"}}     // Not equal
{"field": {"gt": 100}}          // Greater than
{"field": {"gte": 100}}         // Greater than or equal
{"field": {"lt": 100}}          // Less than
{"field": {"lte": 100}}         // Less than or equal

String Operators

{"field": {"contains": "text"}}       // Contains substring
{"field": {"icontains": "text"}}      // Contains (case-insensitive)
{"field": {"startswith": "pre"}}      // Starts with
{"field": {"like": "pat%tern"}}       // SQL LIKE pattern
{"field": {"regex": "^\\d+$"}}        // Regular expression

List Operators

{"field": {"in": ["a", "b", "c"]}}    // In list
{"field": {"nin": ["x", "y"]}}        // Not in list
{"field": {"between": [10, 100]}}     // Between range

Array Operators (PostgreSQL)

{"tags": {"arraycontains": ["a", "b"]}}    // Contains all elements
{"tags": {"arraycontainsany": ["a", "b"]}} // Contains any element
{"tags": {"arraylength": 3}}               // Array has exact length

JSONB Operators (PostgreSQL)

{"meta": {"jsoncontains": {"key": "val"}}}  // JSON contains
{"meta": {"jsonhaskey": "key"}}             // Has key
{"meta": {"jsonpath": "$.store.book[0]"}}   // JSONPath query

Logical Operators

{"AND": [{"status": {"eq": "active"}}, {"price": {"lt": 100}}]}
{"OR": [{"type": {"eq": "A"}}, {"type": {"eq": "B"}}]}
{"NOT": {"deleted": {"eq": true}}}

Dynamic Variables

{"author_Id": {"eq": "$CURRENT_USER"}}    // Current user's ID
{"createdAt": {"gte": "$NOW-DAYS_7"}}     // 7 days ago
{"dueDate": {"lte": "$NOW+MONTHS_1"}}     // 1 month from now

For the complete list of 50+ operators, see the Complete Filter Reference.

Example Usage

Once configured, you can ask your AI assistant to:

  • "Create a products collection with name, price, and description fields"
  • "Add a category relationship to the products collection"
  • "List all products where price is greater than 100"
  • "Create a new user role with read-only access to products"
  • "Show me the server health status"
  • "Enable realtime for the orders collection"

The AI will use the appropriate MCP tools to execute these operations directly on your Baasix backend.

Resources

Plugins Guide

Complete guide to creating, configuring, and publishing Baasix plugins - extend functionality with schemas, routes, hooks, services, and more

Deployment Guide

Complete guide to deploying Baasix in production environments

On this page

MCP Server IntegrationWhat is MCP?FeaturesRemote MCP (Recommended)Enable Remote MCPAuthenticationIDE ConfigurationClaude Code / Anthropic CLIVS Code with GitHub CopilotCursor IDELocal MCPInstallEnvironment VariablesIDE ConfigurationClaude Code / Anthropic CLIClaude DesktopVS Code with GitHub CopilotCursor IDEComparison: Remote vs Local MCPAvailable ToolsSchema Management (13 tools)Item Management (5 tools)Authentication (10 tools)Permissions (9 tools)File Management (3 tools)Reports & Analytics (2 tools)Notifications (3 tools)Realtime (5 tools)Settings & Templates (7 tools)Filter OperatorsComparison OperatorsString OperatorsList OperatorsArray Operators (PostgreSQL)JSONB Operators (PostgreSQL)Logical OperatorsDynamic VariablesExample UsageResources