Data Connectors – Assembled

Data connectors let you pull real-time information from external sources into your workflows. Assembled supports three connector types — API, MCP, and database — each with its own dedicated workflow step. This article covers how to add and configure database and MCP connector steps, map outputs, and set up conditional branching.

What connector types does Assembled support?

Assembled supports three types of data connectors, each suited to a different way of accessing external data:

API — call a pre-configured endpoint
MCP — call a tool from an MCP connector
Database — execute a query against a database connector

Each connector type has its own workflow step. When you build a workflow, you'll select the step type that matches the connector you want to use.

How do I add a data connector step to a workflow?

In the workflow builder, add a new step and select the connector type you want to use: MCP or Database. Then:

Give the step a name (optional).
Select the endpoint, tool, or query you want to call.
Set a Request timeout. The default is 60 seconds.
Optionally, add output branching. You can store outputs as workflow variables.

How do I configure a database connector?

Before you can use a database step in a workflow, you'll need to set up a database connector and at least one query definition. Go to Configure > Tools and Connectors to get started.

When setting up a database connector, you'll provide your connection details and then define one or more queries. Each query includes a SQL statement and any input parameters you want to make available in the workflow step. A single connector can support multiple query definitions.

You need to first add the database connector by clicking on the Add connector button in the top right and selecting Database connector. The connector configuration side sheet will open.

Step 1: Configure connection details

Name: Enter a descriptive name for your connector (e.g., "Customer Database", "CRM Integration"). This name helps identify the connector when managing multiple integrations.

Connector type: Select which database platform you would like to connect to (Snowflake, Databricks, Redshift).

HOST and Port: Enter the host path and port,

Authentication Method: Select how your AI agents authenticate with the database.

Username & Password: Username and password is used to authenticate.
Bearer Token: Provide a bearer token. The token is sent in the Authorization header.
OAuth: OAuth 2.0 client credentials flow, ideal for third-party integrations. Required fields: Client ID (OAuth application client ID), Client Secret (OAuth application secret, securely stored), OAuth URL (token endpoint to exchange credentials for access tokens). The system automatically handles token retrieval and caching, and access tokens are refreshed as needed.

We strongly recommend using a dedicated account for Assembled instead of sharing a personal login. This makes it easier to control access, rotate credentials, and audit usage.

Step 2: Test the connection

After saving the connector, open it and click Test connection.

This confirms that Assembled can:

reach the database host
authenticate successfully
open a live database connection

If the connection test fails, the most common causes are:

incorrect host or port
incorrect username, password, token, or OAuth credentials
incorrect Snowflake warehouse
incorrect Databricks SQL HTTP path
SSL configuration mismatch for PostgreSQL
network allowlist or firewall restrictions blocking Assembled from reaching the database
the Assembled database role does not have enough access to connect

The connection test only verifies connectivity. It does not verify that a specific SQL query will work.

Step 3: Create a SQL query tool

Once the connector is working, create a reusable SQL query tool:

Click on the Create SQL Query button on the connector
Add the SQL query and settings.

Each SQL query tool includes:

Name: A clear internal tool name
Description: Explains what the query does and when the AI should use it
Database connector: The connector to be used for this query. This should be prefilled
SQL query
Max rows
Timeout
Tool type:
- Read-only for SELECTstyle queries
- Write for queries that modify data

In most cases, we recommend starting with Read-only tools.

Adding query parameters

You can make a SQL query reusable by adding placeholders. Use this format:

{{customer_id}}
{{order_id:int}}
{{is_vip:bool}}

Supported placeholder types are:

string
int
float
bool

Example:

SELECT order_status, shipment_eta
FROM support.order_lookup
WHERE order_id = {{order_id:int}}

When the query runs, Assembled passes those values as parameters instead of directly inserting raw text into the SQL string.

Saving query results to a Smart Field

You can optionally toggle on Save results to smart field when creating the SQL query tool.

This is useful when you want later workflow steps to reuse a result from the query. For example, you might:

look up a customer tier
save that value into a Smart Field
branch later in the workflow based on that tier

When you use this setting, Assembled maps the first concrete result column from the query into the selected Smart Field.

Step 4: Test SQL commands

Before using a SQL query tool in a live workflow, test it in the SQL query setup flow.

After saving the SQL query, click Preview query to run the query against the selected connector. If your SQL query uses placeholders, Assembled will prompt you for test values.

When testing, confirm:

the query runs successfully
the correct parameters are being used
the query returns the columns and rows you expect
the query finishes within your timeout
the result shape is appropriate for how the workflow will use it

If the query fails, check:

placeholder names and types
table and column names
schema and catalog references
permissions on the underlying tables or views
row limits and timeouts

Important note on write queries

Testing a Write SQL query runs the command against your live database connection. If the SQL statement performs an INSERT, UPDATE, or DELETE, it can change data during testing.

If you need write access in workflows:

test first in a non-production environment when possible
use narrow permissions
separate read and write tools
make the write query as specific and constrained as possible

How do I configure an MCP connector?

For more details about setting up an MCP connector, you can go to the MCP Connectors for Assembled AI article.

How do I branch a workflow based on connector results?

Each data connector step supports conditional branching based on the result of the connector call. Toggle on Branch based on response to set up your paths. The available branches depend on the connector type:

MCP — success or error
Database — returned rows, no rows, or error

How to use data connectors in Guide steps

Tools and SQL queries you have defined in the Tools and Connectors page can also be used in Guide steps.

Inserting a connector tool in a Guide step

Open the relevant AI Workflow and navigate to the Guide step where the tool should be used.
In the Response instructions field, type @ to open the mention picker.
Select the SQL query tool you want to reference. It appears in your instructions as SQLQuery:tool_name (SQLQuery) and is inserted as a token reference behind the scenes.
Write the surrounding instructions that tell the agent when to call the tool, what parameters to use, and how to handle the response.

Important: The agent calls a tool only when its inserted token reference appears in the instructions. Free-text tool names — for example, just typing "use the get_customer_info tool" — are unreliable. Always use the @ mention picker so the proper token is embedded.

Tool names with special characters are sanitized for the model, which is another reason to use the picker rather than hand-typing names.