BaasixBaasix

MCP Server Integration

The Baasix MCP Server provides a Model Context Protocol (MCP) interface that enables AI assistants to interact directly with your Baasix backend. This allows AI tools like Claude, GitHub Copilot, and Cursor to manage schemas, perform CRUD operations, handle permissions, and more.

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 the Baasix MCP Server, 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 Management12 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
Settings & Utils4 toolsApplication settings and utilities

Quick Start

1. Install the MCP Server

npm install @tspvivek/baasix-mcp-server

2. Create MCP Server Entry Point

Create a mcp-server.js file in your project:

import { startMCPServer } from "@tspvivek/baasix-mcp-server";

if (import.meta.url === `file://${process.argv[1]}`) {
  startMCPServer().catch((error) => {
    console.error('Failed to start MCP server:', error);
    process.exit(1);
  });
}

3. Configure Your AI Tool

Choose the configuration for your preferred AI tool below.

IDE Configuration

Claude Code / Anthropic CLI

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

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

Or add via CLI:

claude mcp add baasix npm run start

VS Code with GitHub Copilot

Create .vscode/mcp.json in your project:

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

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": "node",
      "args": ["/path/to/your/project/mcp-server.js"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "admin@baasix.com",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

Cursor IDE

Add to your Cursor settings or project configuration:

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

Using npx (No Installation)

You can also run the MCP server directly with npx:

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

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.

Available Tools

Schema Management

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

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

Authentication

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

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

ToolDescription
baasix_list_filesList files with metadata
baasix_get_file_infoGet file details
baasix_delete_fileDelete file

Reports & Analytics

ToolDescription
baasix_generate_reportGenerate reports with grouping
baasix_collection_statsGet collection statistics

Notifications

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

Settings & Utilities

ToolDescription
baasix_get_settingsGet application settings
baasix_update_settingsUpdate settings
baasix_server_infoGet server health/info
baasix_sort_itemsReorder items in collection

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"

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

Sample Project

The Baasix Sample Project includes pre-configured MCP files:

  • .mcp.json — Claude Code / Anthropic CLI configuration
  • .vscode/mcp.json — VS Code / GitHub Copilot configuration
  • mcp-server.js — MCP server entry point

Resources

Additional Features Documentation

Additional Features Documentation

Services Reference

Complete reference documentation for Baasix services - ItemsService, MailService, FilesService, and more

On this page

MCP Server IntegrationWhat is MCP?FeaturesQuick Start1. Install the MCP Server2. Create MCP Server Entry Point3. Configure Your AI ToolIDE ConfigurationClaude Code / Anthropic CLIVS Code with GitHub CopilotClaude DesktopCursor IDEUsing npx (No Installation)Environment VariablesAvailable ToolsSchema ManagementItem ManagementAuthenticationPermissionsFile ManagementReports & AnalyticsNotificationsSettings & UtilitiesFilter OperatorsComparison OperatorsString OperatorsList OperatorsArray Operators (PostgreSQL)JSONB Operators (PostgreSQL)Logical OperatorsDynamic VariablesExample UsageSample ProjectResources