XanoScript for Triggers

Introduction

Triggers in XanoScript allow you to define automated responses to specific events across your application. Unlike other primitives, triggers come in several different types, each responding to different kinds of events. XanoScript supports four types of triggers:

Database triggers — Respond to table changes (insert, update, delete)
Workspace triggers — Respond to workspace events (branch changes, deployments)
Realtime triggers — Respond to realtime channel events (messages, joins)
MCP server triggers — Respond to MCP server connection events

Each trigger type has its own unique structure and input schema, but they all follow a similar pattern of declaration, input, stack, and response.

Anatomy

Every XanoScript trigger follows a predictable structure, though the specific components vary by trigger type. Here’s a quick visual overview of the main building blocks — from declaration at the top to settings at the bottom.

You can find more detail about each section by continuing below.

Declaration

Every trigger starts with a declarative header that specifies its type, name, and trigger-specific configuration.

XanoScript

<table_trigger|workspace_trigger|realtime_trigger|mcp_server_trigger> <trigger_name> {
description = "<what this trigger does>"
<trigger_specific_config>
...
}

Element	Required	Description
`trigger_type`	✅	Declares the trigger primitive type.
`trigger_name`	✅	The unique name for the trigger.
`description`	no	Optional human-readable description of the trigger’s purpose.
`trigger_specific_config`	varies	Configuration specific to the trigger type (table, channel, mcp_server, etc.).

Trigger Types

Database Triggers

Database triggers respond to changes in database tables. They can be configured to fire on insert, update, delete, or truncate operations.

XanoScript

table_trigger send_email_on_signup {
  table = "user"
  description = "Sends an email when a user signs up for the service"
  ...
}

Database Trigger Configuration:

table — The table name to monitor for changes
actions — Specifies which database operations trigger the event

Workspace Triggers

Workspace triggers respond to workspace-level events like branch changes, deployments, and other administrative actions.

XanoScript

workspace_trigger notify_on_branch_change {
  description = "Sends an email to the admin on branch activities"
  ...
}

Workspace Trigger Configuration:

actions — Specifies which workspace events trigger the action

Realtime Triggers

Realtime triggers respond to events in realtime channels, such as messages or user joins.

XanoScript

realtime_trigger on_event {
  channel = "my_channel"
  description = "Logs any realtime activity"
  ...
}

Realtime Trigger Configuration:

channel — The realtime channel to monitor
actions — Specifies which realtime events trigger the action

MCP Server Triggers

MCP server triggers respond to MCP server connection events and can modify the toolset and tools available to the server.

XanoScript

mcp_server_trigger on_connect_action {
  mcp_server = "My MCP Server"
  ...
}

MCP Server Trigger Configuration:

mcp_server — The MCP server name to monitor
actions — Specifies which MCP events trigger the action

Section 1: Input

The input block defines the data that will be available to the trigger. Each trigger type has its own specific input schema.

Database Trigger Input:

XanoScript

input {
  json new
  json old
  enum action {
    values = ["insert", "update", "delete", "truncate"]
  }
  text datasource
}

Workspace Trigger Input:

XanoScript

input {
  object to_branch {
    schema {
      int id
      text label
    }
  }
  object from_branch {
    schema {
      int id
      text label
    }
  }
  enum action {
    values = ["branch_live", "branch_merge", "branch_new"]
  }
}

Realtime Trigger Input:

XanoScript

input {
  enum action {
    values = ["message", "join"]
  }
  text channel
  object client {
    schema {
      json extras
      object permissions {
        schema {
          int dbo_id
          text row_id
        }
      }
    }
  }
  object options {
    schema {
      bool authenticated
      text channel
    }
  }
  json payload
}

MCP Server Trigger Input:

XanoScript

input {
  object toolset {
    schema {
      int id
      text name
      text instructions
    }
  }
  object[] tools {
    schema {
      int id
      text name
      text instructions
    }
  }
}

Each trigger type provides different input data based on the event that triggered it. The input schema is automatically provided by Xano based on the trigger type.

Section 2: Stack

The stack block contains the actual logic that will be executed when the trigger fires.

XanoScript

stack {
  util.send_email {
    api_key = ""
    service_provider = "xano"
    subject = "Welcome"
    message = "Thanks for signing up, "|concat:($input.new.name|split:" "|first):""
    bcc = []
    cc = []
    from = ""
    reply_to = ""
    scheduled_at = ""
  } as $email_sent
}

The stack works exactly like other XanoScript primitives:

Functions are called with their parameters
Variables can be created and manipulated
Conditional logic can be applied
Database operations can be performed

The main difference is that triggers have access to the specific input data provided by the triggering event.

Section 3: Response

The response block defines what data your trigger returns (if any). Not all trigger types require a response.

MCP Server Trigger Response:

XanoScript

response {
  value = {toolset: $var.toolset, tools: $tools}
}

Realtime Trigger Response:

XanoScript

response {
  value = $input.payload
}

Database triggers typically don’t need responses
Workspace triggers typically don’t need responses
Realtime triggers can return data to the channel
MCP server triggers must return modified toolset and tools

Settings

Trigger primitives support several optional settings that control which events trigger the action and how the trigger is organized.

Setting	Type	Required	Description
`actions`	object	✅	Specifies which events trigger the action. Keys are event names, values are boolean.
`tags`	array[string]	no	A list of tags used to categorize and organize the trigger in your workspace.

Actions Configuration Examples:Database Trigger Actions:

XanoScript

actions = {insert: true, update: false, delete: false, truncate: false}

Workspace Trigger Actions:

XanoScript

actions = {branch_live: true, branch_merge: true, branch_new: true}

Realtime Trigger Actions:

XanoScript

actions = {message: true, join: true}

MCP Server Trigger Actions:

XanoScript

actions = {connection: true}

Detailed Examples

Database Trigger Example

XanoScript

table_trigger send_email_on_signup {
  table = "user"
  description = "Sends an email when a user signs up for the service"
  input {
    json new
    json old
    enum action {
      values = ["insert", "update", "delete", "truncate"]
    }
    text datasource
  }

  stack {
    util.send_email {
      api_key = ""
      service_provider = "xano"
      subject = "Welcome"
      message = "Thanks for signing up, "|concat:($input.new.name|split:" "|first):""
      bcc = []
      cc = []
      from = ""
      reply_to = ""
      scheduled_at = ""
    } as $email_sent
  }

  tags = ["user actions"]
  actions = {insert: true}
}

MCP Server Trigger Example

XanoScript

mcp_server_trigger on_connect_action {
  mcp_server = "My MCP Server"
  input {
    object toolset {
      schema {
        int id
        text name
        text instructions
      }
    }
    object[] tools {
      schema {
        int id
        text name
        text instructions
      }
    }
  }

  stack {
    var $toolset {
      value = $input.toolset
    }
    var $tools {
      value = $input.tools
    }
    db.get user {
      field_name = "id"
      field_value = $auth.id
    } as $user1
    conditional {
      if ($user1.admin == false) {
        var.update $toolset {
          value = ""
        }
        var.update $tools {
          value = ""
        }
      }
    }
  }

  response {
    value = {toolset: $var.toolset, tools: $tools}
  }

  actions = {connection: true}
}

Workspace Trigger Example

XanoScript

workspace_trigger notify_on_branch_change {
  description = "Sends an email to the admin on branch activities"
  input {
    object to_branch {
      schema {
        int id
        text label
      }
    }
    object from_branch {
      schema {
        int id
        text label
      }
    }
    enum action {
      values = ["branch_live", "branch_merge", "branch_new"]
    }
  }

  stack {
    util.send_email {
      api_key = ""
      service_provider = "xano"
      subject = "Branch activity has occurred"
      message = $input.action
      bcc = []
      cc = []
      from = ""
      reply_to = ""
      scheduled_at = ""
    } as $x1
  }

  actions = {branch_live: true, branch_merge: true, branch_new: true}
}

Realtime Trigger Example

XanoScript

realtime_trigger on_event {
  channel = "my_channel"
  description = "Logs any realtime activity"
  input {
    enum action {
      values = ["message", "join"]
    }
    text channel
    object client {
      schema {
        json extras
        object permissions {
          schema {
            int dbo_id
            text row_id
          }
        }
      }
    }
    object options {
      schema {
        bool authenticated
        text channel
      }
    }
    json payload
  }

  stack {
    db.add log {
      data = {
        created_at   : "now"
        user_message : ""
        agent_message: ""
        why          : ""
        payload      : $input.payload
      }
    } as $log1
  }

  response {
    value = $input.payload
  }

  actions = {message: true, join: true}
}

What’s Next

Now that you understand how to define triggers in XanoScript, here are a few great next steps:

Explore the function reference

Learn about the built-in functions available in the stack to start writing more complex trigger logic.

https://mintlify.s3.us-west-1.amazonaws.com/xano-997cb9ee/images/vscode.svg

Try it out in VS Code

Use the XanoScript VS Code extension with Copilot to write XanoScript in your favorite IDE.

Learn about APIs

Create APIs that can be called by your triggers to build complete automated workflows.

Build Visually

Build with AI

Build with Code

Introduction

Anatomy

Declaration

Trigger Types

Database Triggers

Workspace Triggers

Realtime Triggers

MCP Server Triggers

Section 1: Input

Section 2: Stack

Section 3: Response

Settings

Detailed Examples

Database Trigger Example

MCP Server Trigger Example

Workspace Trigger Example

Realtime Trigger Example

What’s Next

Explore the function reference

Try it out in VS Code

Learn about APIs

Build Visually

Build with AI

Build with Code

​Introduction

​Anatomy

​Declaration

​Trigger Types

​Database Triggers

​Workspace Triggers

​Realtime Triggers

​MCP Server Triggers

​Section 1: Input

​Section 2: Stack

​Section 3: Response

​Settings

​Detailed Examples

​Database Trigger Example

​MCP Server Trigger Example

​Workspace Trigger Example

​Realtime Trigger Example

​What’s Next

Explore the function reference

Try it out in VS Code

Learn about APIs

Introduction

Anatomy

Declaration

Trigger Types

Database Triggers

Workspace Triggers

Realtime Triggers

MCP Server Triggers

Section 1: Input

Section 2: Stack

Section 3: Response

Settings

Detailed Examples

Database Trigger Example

MCP Server Trigger Example

Workspace Trigger Example

Realtime Trigger Example

What’s Next