MCP Integration

The FLXBL MCP (Model Context Protocol) server enables AI assistants in your IDE to design schemas, generate code, and manage your backend through natural language.

Prerequisites

• Node.js 18 or later
• A FLXBL account with an active tenant
• An API key from your FLXBL dashboard
• An MCP-compatible IDE (Cursor, Windsurf, or VS Code with Continue)

Authentication

The FLXBL MCP server supports two authentication modes:

Interactive Mode (Recommended for Development)

When no API key is configured, the MCP server uses interactive authentication. On first use, it will prompt you to log in with your FLXBL credentials (email/password or Google OAuth). Tokens are stored securely and refreshed automatically.

To use interactive mode, simply omit the FLXBL_API_KEY environment variable:

"env": {
  "FLXBL_INSTANCE_URL": "https://api.flxbl.dev"
}

Then use the authenticate tool in your IDE to log in: "Log me in to FLXBL" or "Authenticate with FLXBL"

API Key Mode (Recommended for CI/CD)

For automated environments or when you prefer static credentials, use an API key from your FLXBL dashboard:

1. Log in to your FLXBL dashboard at platform.flxbl.dev
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy the key and add it to your MCP configuration

Important: API keys grant access to your tenant data. Store them securely and never commit them to version control.

IDE Setup

Cursor

Add to your Cursor MCP configuration:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "flxbl": {
      "command": "npx",
      "args": ["@flxbl-dev/mcp"],
      "env": {
        "FLXBL_INSTANCE_URL": "https://api.flxbl.dev",
        "FLXBL_API_KEY": "flxbl_ab12cd34_your_key_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP settings:

// Windsurf MCP settings
{
  "mcp": {
    "servers": {
      "flxbl": {
        "command": "npx",
        "args": ["@flxbl-dev/mcp"],
        "env": {
          "FLXBL_INSTANCE_URL": "https://api.flxbl.dev",
          "FLXBL_API_KEY": "flxbl_ab12cd34_your_key_here"
        }
      }
    }
  }
}

VS Code with Continue

Add to your Continue configuration:

// VS Code with Continue - continue.config.json
{
  "mcpServers": [
    {
      "name": "flxbl",
      "command": "npx",
      "args": ["@flxbl-dev/mcp"],
      "env": {
        "FLXBL_INSTANCE_URL": "https://api.flxbl.dev",
        "FLXBL_API_KEY": "flxbl_ab12cd34_your_key_here"
      }
    }
  ]
}

Available Tools

The FLXBL MCP server provides 19 tools organized into four categories. Once configured, your AI assistant can use these tools through natural language.

Schema Tools

Tools for designing, validating, and managing your schema.

validate_schema

Check a schema for errors without publishing. Catches reserved names, invalid types, breaking changes, and provides design suggestions.

// validate_schema tool
// Checks for errors before publishing

{
  "entities": [{
    "name": "Product",
    "fields": [
      { "name": "id", "type": "STRING", "required": true }  // Error: 'id' is reserved
    ]
  }]
}

// Returns validation errors and design suggestions

publish_schema_version

Create a new schema version with entities and relationships. Handles migrations and breaking change detection automatically.

// publish_schema_version tool
// Creates a new schema version

{
  "entities": [{
    "name": "Product",
    "fields": [
      { "name": "name", "type": "STRING", "required": true },
      { "name": "price", "type": "FLOAT", "required": true }
    ]
  }],
  "relationships": [],
  "description": "Initial product schema"
}

// Returns: schema version ID and migration status

generate_client_types

Generate TypeScript interfaces, Zod schemas, Python models, or language-agnostic API contracts from your schema.

// generate_client_types tool
// Generate code from your schema

// TypeScript interfaces
language: "typescript", format: "interface"

// Zod schemas with API client
language: "typescript", format: "zod"

// Python Pydantic models
language: "python", format: "pydantic"

// Language-agnostic API contract
language: "any", format: "schema"

check_migration_status

Check the status of a running schema migration. Use the migrationId returned from publish_schema_version.

list_schema_templates

Browse available pre-built schema templates for common use cases like e-commerce, blog, CRM, project management, and more.

Data Tools

Tools for querying, creating, updating, and managing your data.

entity_crud

Perform CRUD operations on dynamic entities. Supports create, read, update (full replace), patch (partial update), and delete actions.

// entity_crud tool
// Perform CRUD operations on dynamic entities

// Create a product
{
  "action": "create",
  "entityName": "Product",
  "data": { "name": "Widget", "price": 29.99 }
}

// Read by ID
{
  "action": "read",
  "entityName": "Product",
  "entityId": "node_abc123"
}

// Update (full replace)
{
  "action": "update",
  "entityName": "Product",
  "entityId": "node_abc123",
  "data": { "name": "Updated Widget", "price": 34.99 }
}

// Patch (partial update)
{
  "action": "patch",
  "entityName": "Product",
  "entityId": "node_abc123",
  "data": { "price": 24.99 }
}

// Delete
{
  "action": "delete",
  "entityName": "Product",
  "entityId": "node_abc123"
}

query_entities

Execute complex queries with filtering, relationship traversal, field selection, ordering, and pagination. Supports all Query DSL operators.

// query_entities tool
// Execute complex queries with filtering and traversal

// Simple query with filter
{
  "entityName": "Product",
  "where": { "price": { "$gte": 50 } },
  "limit": 20,
  "orderBy": [{ "field": "createdAt", "direction": "desc" }]
}

// Query with relationship traversal
{
  "entityName": "Customer",
  "where": { "status": { "$eq": "active" } },
  "traverse": [{
    "relationship": "PLACED_ORDER",
    "direction": "out",
    "select": ["id", "total", "status"],
    "where": { "total": { "$gt": 100 } }
  }],
  "select": ["id", "name", "email"],
  "limit": 50
}

// Supported operators:
// $eq, $ne, $gt, $gte, $lt, $lte
// $in, $notIn, $isNull
// $contains, $startsWith, $endsWith
// $and, $or

Learn more about query operators in the Query DSL documentation.

batch_operations

Perform bulk create, update, or delete operations on up to 1,000 items. All operations are atomic (all-or-nothing).

// batch_operations tool
// Perform bulk create, update, delete (max 1000 items)

// Batch create
{
  "action": "batch_create",
  "entityName": "Product",
  "items": [
    { "name": "Item 1", "price": 10 },
    { "name": "Item 2", "price": 20 }
  ]
}

// Batch update
{
  "action": "batch_update",
  "entityName": "Product",
  "items": [
    { "id": "node_abc", "data": { "price": 15 } },
    { "id": "node_def", "data": { "price": 25 } }
  ]
}

// Batch delete
{
  "action": "batch_delete",
  "entityName": "Product",
  "ids": ["node_abc", "node_def", "node_ghi"]
}

manage_relationships

Create, list, and delete typed relationships between entities. Supports relationship properties and directional queries.

// manage_relationships tool
// Create, list, and delete typed relationships

// Create a relationship
{
  "action": "create",
  "entityName": "Product",
  "entityId": "node_abc",
  "relationshipName": "BELONGS_TO",
  "targetId": "node_category_xyz",
  "properties": { "addedAt": "2025-01-15T10:30:00Z" }
}

// List relationships
{
  "action": "list",
  "entityName": "Product",
  "entityId": "node_abc",
  "relationshipName": "BELONGS_TO",
  "direction": "out"  // "out", "in", or "both"
}

// Delete a relationship
{
  "action": "delete",
  "entityName": "Product",
  "entityId": "node_abc",
  "relationshipName": "BELONGS_TO",
  "targetId": "node_category_xyz"
}

execute_graphql

Execute GraphQL queries and mutations directly. Useful for complex operations or when you need full GraphQL flexibility.

// execute_graphql tool
// Execute GraphQL queries and mutations

// Query with variables
{
  "tenantId": "your-tenant-id",
  "query": `
    query GetProducts($minPrice: Float!) {
      products(where: { price: { gte: $minPrice } }) {
        id
        name
        price
      }
    }
  `,
  "variables": { "minPrice": 50 }
}

// Mutation
{
  "tenantId": "your-tenant-id",
  "query": `
    mutation CreateProduct($input: CreateProductInput!) {
      createProduct(input: $input) {
        id
        name
      }
    }
  `,
  "variables": {
    "input": { "name": "New Widget", "price": 39.99 }
  }
}

Security Tools

Tools for managing access control, API keys, and authentication.

manage_access_keys

Create, list, and delete scoped API keys for your integrations. Keys can be restricted to specific entities and operations.

// manage_access_keys tool
// Create, list, and delete scoped API keys

// List all keys
{ "action": "list" }

// Create a new key with specific scopes
{
  "action": "create",
  "name": "mobile-app-readonly",
  "scopes": [
    "entity:Product:read",
    "entity:Category:read"
  ]
}

// Delete a key
{
  "action": "delete",
  "keyId": "key_abc123"
}

Learn more about API keys in the API Keys documentation.

configure_identity

View and update authentication settings including token expiry, password policies, and email verification requirements.

// configure_identity tool
// Manage authentication settings

// View current configuration
{ "action": "get" }

// Update token expiry and password policy
{
  "action": "update",
  "accessTokenExpiryMinutes": 30,
  "refreshTokenExpiryDays": 14,
  "minPasswordLength": 12,
  "requireEmailVerification": true
}

Learn more about identity settings in the Identity Configuration documentation.

manage_users

Manage team members in your FLXBL tenant. List users, send invitations, remove users, and manage role assignments.

// manage_users tool
// Manage team members in your FLXBL tenant

// List all users
{ "action": "list" }

// Invite a new user
{
  "action": "invite",
  "email": "teammate@company.com",
  "roleId": "role_admin"
}

// Remove a user
{
  "action": "remove",
  "userId": "user_abc123"
}

// Get user's roles
{
  "action": "get_roles",
  "userId": "user_abc123"
}

// Assign role to user
{
  "action": "assign_role",
  "userId": "user_abc123",
  "roleId": "role_editor"
}

Learn more about users in the User Management documentation.

manage_roles

Manage roles and permissions. Create custom roles, assign permissions, and control access at a granular level.

// manage_roles tool
// Manage roles and permissions

// List all roles
{ "action": "list" }

// List available permissions
{ "action": "list_permissions" }

// Create a custom role
{
  "action": "create",
  "name": "Product Manager",
  "description": "Can manage products and categories",
  "permissions": [
    "entity:Product:create",
    "entity:Product:read",
    "entity:Product:update",
    "entity:Category:read"
  ]
}

// Update a role
{
  "action": "update",
  "roleId": "role_abc",
  "permissions": ["entity:*:read"]
}

Learn more about roles in the Access Control documentation.

API Tools

Tools for API documentation and event-driven integrations.

get_api_spec

Get the OpenAPI 3.0 specification for your active schema. Returns complete REST API documentation including endpoints, schemas, and query parameters.

// get_api_spec tool
// Get OpenAPI 3.0 specification

// Full JSON spec
{ "format": "json" }

// Condensed summary
{ "format": "summary" }

// Returns: Complete REST API documentation including
// endpoints, request/response schemas, and query parameters

get_graphql_schema

Get the GraphQL SDL (Schema Definition Language) for your active schema. Returns type definitions, queries, mutations, and subscriptions.

// get_graphql_schema tool
// Get GraphQL SDL (Schema Definition Language)

// No parameters required
{}

// Returns: Type definitions, queries, mutations,
// subscriptions, and relationship types

manage_webhooks

Set up webhook notifications for entity lifecycle events. Configure which events trigger notifications and where they're sent.

// manage_webhooks tool
// Set up event notifications for your app

// List all webhooks
{ "action": "list" }

// Create a webhook for order events
{
  "action": "create",
  "targetUrl": "https://your-app.com/webhooks",
  "eventTypes": ["entity.created", "entity.updated"],
  "entityNames": ["Order"],
  "schemaName": "production"
}

// Update webhook status
{
  "action": "update",
  "webhookId": "wh_xyz",
  "isActive": false
}

// Delete a webhook
{
  "action": "delete",
  "webhookId": "wh_xyz"
}

Learn more about webhooks in the Webhooks documentation.

Available Resources

Resources provide context to your AI assistant about your current schema and API:

Example Workflows

Designing a New Schema

1. Open your IDE chat
2. Ask: "Help me design a schema for a blog platform with posts, authors, and comments"
3. The AI uses the design_flxbl_schema prompt to guide you
4. Review the suggested schema
5. Ask: "Validate this schema"
6. Fix any issues, then: "Publish this schema"

Adding Features to Existing Schema

1. The AI reads your current schema via flxbl://schema/active
2. Ask: "Add a Reviews feature to my Product entity"
3. The AI suggests schema changes using relationships
4. Validate and publish the new version
5. Check migration status if needed

Generating Client Code

1. Ask: "Generate TypeScript interfaces for my schema"
2. The AI uses generate_client_types
3. Copy the generated code to your project

Setting Up API Keys

1. Ask: "Create a read-only API key for my mobile app"
2. The AI uses manage_access_keys with appropriate scopes
3. Store the returned key securely
4. Use in your mobile app's Authorization header

Configuring Webhooks

1. Ask: "Set up a webhook to notify my server when orders are created"
2. The AI uses manage_webhooks with your endpoint URL
3. Store the signing secret securely
4. Implement signature verification in your webhook handler

Adjusting Security Settings

1. Ask: "What are my current authentication settings?"
2. The AI uses configure_identity to fetch configuration
3. Ask: "Increase token expiry to 30 minutes"
4. The AI updates the configuration

Example Prompts

Try these prompts with your AI assistant:

Schema Design

• "Help me design a schema for an e-commerce platform"
• "Add a MANY_TO_MANY relationship between Products and Tags"
• "Validate my schema and check for breaking changes"
• "What schema templates are available?"

Code Generation

• "Generate Zod schemas for my FLXBL schema"
• "Create TypeScript interfaces for all my entities"
• "Generate Python Pydantic models"

Data Operations

• "Create a new Product with name 'Widget' and price 29.99"
• "Find all products with price greater than $50"
• "Update all products in the 'Electronics' category to have a 10% discount"
• "Show me customers and their orders from the last 30 days"
• "Bulk import these 100 products from my CSV"
• "Create a relationship between Product X and Category Y"

Security & Access

• "Create a read-only API key for my frontend"
• "List all my API keys"
• "Delete the API key called 'old-backend'"
• "What are my current authentication settings?"
• "Require 12-character minimum passwords"

Integrations

• "Set up a webhook for Order events"
• "List my active webhooks"
• "Disable the webhook for the old endpoint"

Troubleshooting

"Configuration Error: Missing required environment variables"

Ensure both FLXBL_INSTANCE_URL and FLXBL_API_KEY are set in your MCP configuration.

"Invalid or expired API key"

Your API key may have expired or been revoked. Generate a new one from the FLXBL dashboard.

"Could not verify FLXBL connectivity"

Check that:

• Your FLXBL_INSTANCE_URL is correct
• Your network can reach the FLXBL API
• The FLXBL service is operational

MCP Server Not Starting

Check your IDE's MCP output panel. Common issues:

• Node.js version too old (requires 18+)
• npm/npx not in PATH
• Missing environment variables

Next Steps

• Schema Design - Learn schema best practices
• API Keys - Create and manage scoped API keys
• Webhooks - Set up event notifications
• Identity Configuration - Configure authentication settings
• API Reference - REST and GraphQL documentation