Xano Backend Builder

What this skill does

# Xano Backend Builder

Build serverless backend infrastructure using Xano's no-code platform through MCP (Model Context Protocol) server integration. Create databases, REST APIs, custom functions, and business logic using XanoScript without traditional coding.

## Instructions

### Prerequisites

1. **Xano Account and Workspace**:
   - Sign up at https://xano.com
   - Create or access an existing workspace

2. **MCP Access Token and URL**:
   - Navigate to workspace Settings → Metadata API & MCP Server
   - Copy your **MCP Server URL** (e.g., `https://x8ki-letl-twmt.n7.xano.io/mcp`)
   - Generate an **Access Token** with appropriate scopes
   - **CRITICAL**: Token appears only once - save it securely
   - **WARNING**: MCP operations can modify/delete data - use backups for production

3. **MCP Server Configuration**:
   This plugin includes MCP server configuration that connects automatically when enabled.

   **Set environment variables**:
   ```bash
   export XANO_MCP_URL="https://your-workspace.xano.io/mcp"
   export XANO_MCP_TOKEN="your_access_token_here"
   ```

   Or add to your shell profile (`~/.zshrc`, `~/.bashrc`):
   ```bash
   # Xano MCP Configuration
   export XANO_MCP_URL="https://your-workspace.xano.io/mcp"
   export XANO_MCP_TOKEN="your_access_token_here"
   ```

   **Restart Claude Code** after setting environment variables.

   The Xano MCP server will start automatically when this plugin is enabled, and Xano tools will be available in your Claude Code session.

### Understanding Xano Architecture

**Xano Components**:
- **Database Tables**: Store structured data with relationships
- **API Endpoints**: REST endpoints for CRUD operations and custom logic
- **Function Stack**: Visual programming interface using XanoScript
- **Background Tasks**: Scheduled or triggered async operations
- **AI Agents**: Custom AI-powered functions and workflows

**XanoScript Basics**:
Xano uses a proprietary syntax called XanoScript for defining logic. Key characteristics:
- **Namespace functions**: `db.query`, `array.push`, `var.update`
- **Variable assignment**: Use `as $variable_name`
- **Filters**: Transform data with pipe syntax `|filter_name:option`
- **Primitives**: Top-level constructs (API, function, table, etc.)

**Important**: XanoScript syntax is unique to Xano. When working with XanoScript:
- Look for examples in Xano documentation or API responses
- Test syntax incrementally
- Reference [docs/xanoscript-reference.md](docs/xanoscript-reference.md) for detailed syntax guide

### Workflow

1. **Understand the requirement**:
   - What data needs to be stored? (database design)
   - What API endpoints are needed? (GET, POST, PUT, DELETE)
   - What business logic is required? (transformations, validations, external API calls)
   - What integrations are needed? (webhooks, OAuth, third-party APIs)

2. **Design the database schema**:
   - Identify entities (tables) and relationships
   - Define fields with appropriate data types
   - Consider indexes for performance
   - Use MCP tools to create tables:
     ```
     Use Xano MCP tools to create a table with specified fields
     ```

3. **Create API endpoints**:
   - Define REST endpoints (GET, POST, PUT, DELETE)
   - Configure authentication requirements
   - Set up input parameters and validation
   - Build response structure
   - Use MCP tools to create API endpoints

4. **Implement business logic with XanoScript**:
   - Use the Function Stack to build logic
   - **Key XanoScript patterns**:
     - Query database: `db.query table_name { filters } as $results`
     - Create variable: `var $my_var { value = "initial" }`
     - Update variable: `var.update $my_var { value = "new" }`
     - Loop through data: `foreach ($items) { each as $item { } }`
     - Conditional logic: `conditional { if ($condition) { } else { } }`
     - Transform data: `$data|filter_name:option`
   - Reference [docs/xanoscript-reference.md](docs/xanoscript-reference.md) for detailed syntax

5. **Test the implementation**:
   - Use Xano's built-in API testing interface
   - Verify database operations
   - Check response formats
   - Test error handling
   - Validate authentication flows

6. **Generate API documentation**:
   - Use MCP tools to generate OpenAPI specifications
   - Share with frontend developers
   - Document authentication requirements

7. **Deploy and monitor**:
   - Test in Xano's staging environment
   - Deploy to production
   - Monitor API usage and performance
   - Set up error logging

### Common Use Cases

**1. REST API for CRUD operations**:
- Create database table
- Generate default API endpoints
- Add authentication
- Customize response format

**2. Webhook receiver**:
- Create API endpoint to receive webhooks
- Parse incoming payload
- Process data (store, transform, forward)
- Return appropriate response

**3. External API integration**:
- Create function to call external API
- Handle authentication (API keys, OAuth)
- Parse response and transform data
- Store or return processed data

**4. Data transformation pipeline**:
- Query source data
- Apply filters and transformations
- Aggregate or format results
- Return processed data

**5. Scheduled background tasks**:
- Create background task
- Define schedule (cron-like)
- Implement logic (cleanup, notifications, sync)
- Handle errors and retries

### XanoScript Guidelines

**Be mindful of syntax differences**:
- XanoScript is NOT JavaScript/Python
- Function syntax: `namespace.function` (e.g., `db.query`, not `db_query`)
- Variables always use `$` prefix: `$my_variable`
- Assignment uses `as` keyword: `db.query users {} as $users`
- Filters use pipe: `$users|count`, not `count($users)`

**When uncertain about syntax**:
1. Check [docs/xanoscript-reference.md](docs/xanoscript-reference.md) for examples
2. Ask Xano MCP to show existing function examples
3. Test small snippets first
4. Reference official documentation: https://docs.xano.com/xanoscript/key-concepts

**Common XanoScript mistakes**:
- ❌ `db_query("users")` → ✅ `db.query users { }`
- ❌ `var my_var = "value"` → ✅ `var $my_var { value = "value" }`
- ❌ `count($array)` → ✅ `$array|count`
- ❌ `if (condition) {}` → ✅ `conditional { if ($condition) { } }`

### Available MCP Tools

Once the plugin is enabled and environment variables are set, the Xano MCP server provides these tools automatically:

- **Database operations**: Creating and modifying tables, schemas, relationships
- **API development**: Building endpoints, configuring routes and methods
- **Authentication**: Managing API keys, JWT, OAuth configurations
- **Custom functions**: Creating business logic with XanoScript
- **Background tasks**: Setting up scheduled and triggered jobs
- **Documentation**: Generating OpenAPI specs for frontend integration
- **Workspace management**: Configuring settings and permissions

**Using MCP tools**: Simply ask Claude to perform Xano operations naturally (e.g., "Create a users table with email and name fields"). Claude will automatically use the appropriate Xano MCP tools to execute your requests.

### Error Handling

**Common issues**:
- **Authentication errors**: Verify MCP token is correct and has required scopes
- **XanoScript syntax errors**: Check function names, variable syntax, and filter usage
- **Permission errors**: Ensure token has appropriate permissions for operation
- **Rate limiting**: Xano has API rate limits - implement appropriate throttling

**Debugging approach**:
1. Test XanoScript in Xano's visual editor first
2. Validate data types and structure
3. Check API endpoint configuration
4. Review error messages carefully
5. Use Xano's built-in debugger and logs

### Security Best Practices

1. **Token management**:
   - Never commit MCP tokens to version control
   - Use environment variables or secure storage
   - Rotate tokens periodically

2. **API security**:
   - Implement authentication on sensitive endpoints
   - Use API key authentication or JWT
   - Validate and sanitize