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)

Getting an API Key

  1. Log in to your FLXBL dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New Key
  4. Copy the key (it won't be shown again)
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

Once configured, your AI assistant can use these tools:

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.

Available Resources

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

Resource URI Description
flxbl://about Product information about FLXBL architecture
flxbl://tenant Your tenant context including tenantId
flxbl://schema/active Current schema with entities and relationships
flxbl://context Formatted schema summary for LLM context
flxbl://api/graphql GraphQL SDL schema with usage instructions
flxbl://templates Available schema templates

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

Example Prompts

Try these prompts with your AI assistant:

  • "Help me design a schema for an e-commerce platform"
  • "Generate Zod schemas for my FLXBL schema"
  • "Add a MANY_TO_MANY relationship between Products and Tags"
  • "Show me how to query products with their categories"
  • "What schema templates are available?"
  • "Validate my schema and check for breaking changes"

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