Xano MCP Documentation

How It Works

This isn’t a traditional SDK - it’s an AI guidance system designed specifically for agent interaction. Here’s the real story.

The Agentic Language Concept

The Challenge

AI agents have specific limitations that traditional development tools don’t account for:

AI agents are “gullible and don’t learn outside the immediate conversation” (Andrej Karpathy)

They don’t know:

  • XanoScript syntax rules and forbidden patterns
  • Xano’s runtime limitations and error messages
  • What will fail mysteriously at deployment
  • Best practices for reviewable, maintainable code
  • When to add pagination, error handling, validation

The Solution: Real-Time Guidance

This tool provides three layers of intelligence:

1. Immediate Feedback (Before Generation)

When AI attempts a database query, the SDK hints:

💡 Consider adding pagination for this list endpoint
💡 Watch for these pagination variables: curPage, itemsTotal, itemsReceived
💡 Use filters instead of expressions for better performance

2. Enforcement (Before Deployment)

Catches issues that would fail in Xano:

❌ Forward-slash comments not allowed in XanoScript
💡 Use /* */ style comments instead

❌ Missing required field: name
💡 Add .input('name', 'text', { required: true })

❌ Invalid filter combination
💡 Use separate filters instead of nested conditions

3. Transformation (During Deployment)

Converts JavaScript-like SDK to opinionated, filter-based XanoScript:

// SDK Input
.dbQuery('users', { 
  pagination: { page: '$input.page', per_page: '$input.per_page' }
})
 
// Transforms to proper XanoScript with filters
// (not green expression syntax)

The Transformation (Critical to Understand)

What You Say

"Create a users search endpoint with pagination"

What the AI Generates (SDK)

const endpoint = create('users/search', 'GET')
  .description('Search users with pagination')
  .input('page', 'int', { default: 1 })
  .input('per_page', 'int', { default: 20, max: 100 })
  .input('search', 'text', { required: false })
  .dbQuery('users', {
    filters: [
      {
        field: 'name',
        operator: 'contains',
        value: '$input.search'
      }
    ],
    pagination: {
      page: '$input.page',
      per_page: '$input.per_page'
    }
  }, 'results')
  .response({
    items: '$results.items',
    pagination: {
      page: '$results.curPage',
      total: '$results.itemsTotal',
      per_page: '$input.per_page'
    }
  });
 
return endpoint.build().script;

This is JavaScript-like syntax designed for AI comprehension.

What Gets Deployed (XanoScript)

The middleware transforms this into filter-based XanoScript:

/* Search users with pagination */

/* Define inputs */
var page = $input.page
var per_page = $input.per_page
var search = $input.search

/* Query database with filters */
var results = query_all_users({
  filter: {
    name: {
      contains: search
    }
  },
  pagination: {
    page: page,
    per_page: per_page
  }
})

/* Return structured response */
return {
  items: results.items,
  pagination: {
    page: results.curPage,
    total: results.itemsTotal,
    per_page: per_page
  }
}

Key differences:

  • Uses Xano’s query filters (not green expressions)
  • Proper XanoScript comment syntax (/* */ not //)
  • Variable declarations follow Xano patterns
  • Looks clean and reviewable in Xano GUI
  • Non-developers can understand the logic

Opinionated Output (Why It Matters)

Filter-Based vs Expression-Based

This tool generates filter-based XanoScript:

/* ✓ Filter-based (what we generate) */
query_all_users({
  filter: {
    status: { equals: 'active' },
    created_at: { gt: last_week }
  }
})

NOT expression-based:

/* ✗ Expression-based (harder to review) */
query_all_users().filter(user => 
  user.status == 'active' && user.created_at > last_week
)

Why Filters?

  1. Reviewable - Business logic is clear in Xano GUI
  2. Maintainable - Non-developers can modify filters
  3. Performant - Xano optimizes filter-based queries
  4. Debuggable - Easier to trace issues

The One-to-One Mapping

Every SDK method maps directly to XanoScript:

SDK MethodXanoScript Output
.input('name', 'text')Input parameter definition
.dbQuery('table', {})Database query with filters
.apiRequest('url', 'GET')External API call
.if(condition)Conditional logic block
.var('name', value)Variable declaration
.response({})Return statement

This consistency helps AI learn patterns across conversations.

Slug-Level Protections

Purpose: Course-Correct Misguided AI

The slug URL you configure restricts AI to your chosen workspace. This isn’t security against malicious users - it’s guardrails for AI agents that forget context.

How It Works

Without slugs (chaos):

AI: "Let me check your database..."
[Accesses wrong workspace]
AI: "You have tables: table1, table2..."
[Wrong tables!]

With slugs (focused):

AI: "Let me check your database..."
[Slug enforces correct workspace]
AI: "You have tables: users, products..."
[Correct workspace!]

What Slugs Prevent

  1. Wrong Workspace Access

    • AI tries to access workspace A
    • Slug redirects to configured workspace B
    • Helpful error: “You’re configured for workspace B”

  2. Forbidden Operations

    • AI attempts to delete production data
    • Slug provides warning and confirmation prompt
    • Context reminder about current workspace

  3. Context Loss

    • AI forgets which instance it’s working in
    • Slug URL contains workspace/instance metadata
    • AI gets re-oriented with helpful hints

Example: Course-Correction in Action

AI forgets and tries wrong workspace:

Request: Get tables from workspace 'staging'
Response: ❌ Your slug is configured for workspace 'production'
          💡 To work in staging, create a new slug at mcp.snappy.ai
          💡 Current workspace: production
          💡 Available tables: users, orders, products

Real-Time Guidance Examples

Pagination Hints

When AI creates list endpoint:

// AI writes:
.dbQuery('products', {}, 'items')
 
// SDK hints:
💡 Hint: List endpoints should include pagination
💡 Consider adding:
   .input('page', 'int', { default: 1 })
   .input('per_page', 'int', { default: 20 })
   pagination: { page: '$input.page', per_page: '$input.per_page' }

Validation Hints

When AI forgets validation:

// AI writes:
.input('email', 'text')
 
// SDK hints:
💡 Hint: Email inputs should include validation
💡 Consider: .input('email', 'email', { required: true })

Performance Hints

When AI uses expensive patterns:

// AI writes:
.dbQuery('users', { all: true })
 
// SDK hints:
⚠️  Warning: Querying all records can be slow
💡 Consider adding pagination or filters
💡 Example: .dbQuery('users', { limit: 100 })

Error Prevention

When AI uses forbidden syntax:

// AI writes:
// This is a comment
 
// SDK prevents:
❌ Forward-slash comments not allowed in XanoScript
💡 Use /* */ instead: /* This is a comment */
✓ Automatically corrected in output

The Complete Flow

1. You Request Something

You: "Create a products list endpoint with search and pagination"

2. AI Interprets & Generates SDK

The AI:

  • Understands your requirements
  • Generates JavaScript-like SDK code
  • Receives real-time hints about pagination
  • Adds proper inputs and filters
const endpoint = create('products/list', 'GET')
  .description('List products with search and pagination')
  .input('page', 'int', { default: 1 })
  .input('per_page', 'int', { default: 20, max: 100 })
  .input('search', 'text', { required: false })
  .dbQuery('products', {
    filters: [
      {
        field: 'name',
        operator: 'contains',
        value: '$input.search'
      }
    ],
    pagination: {
      page: '$input.page',
      per_page: '$input.per_page'
    }
  }, 'results')
  .response({
    items: '$results.items',
    pagination: {
      page: '$results.curPage',
      total: '$results.itemsTotal'
    }
  });

3. Middleware Transforms to XanoScript

The SDK:

  • Validates the structure
  • Enforces Xano constraints
  • Transforms to filter-based XanoScript
  • Optimizes for reviewability

4. Deploys to Xano

The endpoint:

  • Gets created in your workspace
  • Appears clean in Xano GUI
  • Is reviewable by non-developers
  • Works immediately

5. You Test with cURL

curl "https://your-instance.xano.io/api:v1/products/list?page=1&per_page=20&search=laptop"

Response:

{
  "items": [...],
  "pagination": {
    "page": 1,
    "total": 42
  }
}

Total time: 30 seconds

Why This Architecture Works

For AI Agents

  • Clear patterns - JavaScript-like syntax AI already understands
  • Immediate feedback - Hints guide toward correct implementation
  • Error prevention - Catches mistakes before deployment fails
  • Context retention - Slug protections keep AI focused

For Developers

  • Fast iteration - Build and test in seconds
  • Reviewable output - Check XanoScript in Xano GUI
  • Maintainable - Non-developers can modify logic
  • Debuggable - Clear transformation path

For Non-Technical Users

  • No code required - Just describe what you need
  • Reviewable logic - See business rules in Xano
  • Modifiable - Change filters without code knowledge
  • Documented - Auto-generated API docs

The Next.js Integration Pattern

This architecture is perfect for Next.js projects:

Traditional Approach (What We Avoid)

Next.js App
├── /app
│   └── /api
│       ├── auth/route.ts      ← Backend code in frontend repo
│       ├── products/route.ts  ← Mixed concerns
│       └── orders/route.ts    ← Deployment coupling
└── /components

Problems:

  • Backend logic in frontend repository
  • Deployment coupling (can’t deploy frontend without backend)
  • Code review bottleneck (developers needed for all changes)
  • Mixed concerns (frontend and backend in same codebase)

Modern Approach (What We Enable)

Next.js App (Frontend only)
├── /app
├── /components
└── /lib
    └── api.ts    ← Service layer calls Xano

Xano (Backend via MCP)
├── Database Tables
├── API Endpoints
└── Business Logic
    (All reviewable in GUI)

Benefits:

  • Clean separation of concerns
  • Independent deployment (frontend and backend)
  • Business logic reviewable by non-developers
  • AI builds both frontend and backend
  • Fast iteration on backend (no deployment pipeline)

Example: User Registration Flow

Next.js Component:

// components/auth/register-form.tsx
import { xanoApi } from '@/lib/api'
 
export function RegisterForm() {
  const handleSubmit = async (data: RegisterData) => {
    const result = await xanoApi.auth.register(data)
    if (result.success) {
      // Handle success
    }
  }
  
  return <form onSubmit={handleSubmit}>...</form>
}

Service Layer:

// lib/api.ts
export const xanoApi = {
  auth: {
    register: async (data: RegisterData) => {
      return fetch('https://your-instance.xano.io/api:v1/auth/register', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      }).then(r => r.json())
    }
  }
}

Xano Backend (Built via MCP):

Just tell the AI:

"Create a registration endpoint with email validation and password hashing"

Result:

  • Frontend: Clean React component
  • Service: Type-safe API calls
  • Backend: Reviewable logic in Xano GUI
  • Testing: cURL commands for immediate verification

Under the Hood

The Three-Tier System

You (Claude Code or Claude Desktop)
    ↓
AI Model (Claude, GPT-4, etc.)
    ↓
MCP Server (105 specialized tools)
    ↓
Middleware (SDK transformation)
    ↓
Xano Instance (Your backend)

Component Responsibilities

You: Describe what you want in plain English

AI Model:

  • Interprets your request
  • Generates SDK code
  • Receives hints and guidance
  • Handles conversation context

MCP Server:

  • Provides 105 specialized tools
  • Routes requests to middleware
  • Manages workspace access
  • Enforces slug protections

Middleware:

  • Transforms SDK to XanoScript
  • Validates structure
  • Enforces Xano constraints
  • Provides real-time hints

Xano:

  • Stores your data
  • Runs your endpoints
  • Serves your APIs
  • Hosts reviewable business logic

Key Takeaways

This Is Not Just Code Generation

It’s a guidance system that:

  • ✓ Teaches AI about Xano constraints
  • ✓ Enforces best practices automatically
  • ✓ Generates reviewable, maintainable output
  • ✓ Provides immediate testing feedback
  • ✓ Course-corrects misguided AI

The Transformation Matters

SDK → XanoScript isn’t just conversion:

  • ✓ JavaScript-like → Filter-based
  • ✓ AI-friendly → Human-reviewable
  • ✓ Development syntax → Production code
  • ✓ Gullible agent → Guided implementation

Slug Protections Are Guardrails

Not security - course-correction:

  • ✓ Keeps AI focused on your workspace
  • ✓ Prevents accidental wrong-workspace access
  • ✓ Provides context when AI forgets
  • ✓ Helpful errors instead of mysterious failures

Ready to Build?

Now that you understand how it works:

Get Started → - Set up your workspace and build your first endpoint

Best Practices → - Learn the iterative workflow and testing patterns

Explore Capabilities → - See what you can build