> For the complete documentation index, see [llms.txt](https://guide.tiledesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.tiledesk.com/tiledesk-mcp-tools/tiledesk-data-tables-mcp.md).

# Tiledesk Data Tables MCP

The **Tiledesk Data Tables MCP** lets an AI Agent read and write structured data directly from an AI Prompt.

Instead of adding separate workflow actions for every table operation, you can describe what the Agent should do and let it inspect the schema, insert records, search rows, update values, or upsert data automatically.

<figure><img src="https://1328774413-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVguk6y5OMn3pAaHZSiwU%2Fuploads%2FanoNZWASdhlWBQ1v5XsP%2FScreenshot%202026-09-28%20at%2013.29.43.png?alt=media&amp;token=58e9d96b-2589-4d26-bcbc-1ddc0fd4e035" alt=""><figcaption></figcaption></figure>

### Why use the Data Tables MCP

The main benefit is that information collected during a conversation can become structured, reusable data without manually building a separate action for every field.

* Save leads, requests, contacts, or other structured data directly from an AI workflow.
* Read existing rows and use them as part of the next AI decision.
* Update records without creating separate workflow branches for each field.
* Use upsert logic to update an existing record or create a new one automatically.
* Combine Data Tables with the Communicator and Knowledge Base MCPs in the same AI Prompt.

In this guide, we will create a simple **Leads** table and let the AI Agent save contact information together with a basic lead temperature: **cold**, **mid**, or **hot**.

### Available tools

* **DATATABLE\_LIST\_TABLES** — returns the Data Tables available in the project.
* **DATATABLE\_SEARCH\_TABLES** — finds the most relevant table from a natural-language query.
* **DATATABLE\_GET\_TABLE\_SCHEMA** — returns the table structure, including exact column names and field types.
* **DATATABLE\_QUERY\_ROWS** — retrieves rows from a table, with optional filtering conditions.
* **DATATABLE\_INSERT\_ROW** — inserts a new row.
* **DATATABLE\_UPDATE\_ROWS** — updates one or more existing rows.
* **DATATABLE\_UPSERT\_ROWS** — updates a matching row or inserts a new one when no match exists.
* **DATATABLE\_DELETE\_ROWS** — deletes matching rows.

<figure><img src="https://1328774413-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVguk6y5OMn3pAaHZSiwU%2Fuploads%2F5hdtCO7nZOgBwMgnebbr%2FUntitled.001.001.png?alt=media&amp;token=f4fa02e9-e2f7-4ad5-b653-17396c7c43b9" alt=""><figcaption></figcaption></figure>

### Set up a simple lead capture flow

{% stepper %}
{% step %}

#### Create the Leads table

Create a Data Table called **Leads** with these columns:

* `full_name` — text
* `email` — text
* `company` — text
* `lead_temperature` — text

For `lead_temperature`, use these values:

* **hot** — clear use case and immediate interest in moving forward.
* **mid** — relevant use case but still evaluating or without an immediate next step.
* **cold** — general interest with no clear active project or short-term need.

<figure><img src="https://1328774413-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVguk6y5OMn3pAaHZSiwU%2Fuploads%2FdJa83b9ILa8qoQJz5PdR%2FUntitled.001.001.png?alt=media&amp;token=9db2086f-bcc2-4d5f-8101-2807f3c02701" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Enable the Data Tables MCP

Open the AI Prompt action where you want the Agent to work with the table.

Enable the **Tiledesk Data Tables MCP** so the Agent can access the Data Tables tools.
{% endstep %}

{% step %}

#### Always read the schema first

Before inserting, querying, updating, deleting, or upserting rows, use **DATATABLE\_GET\_TABLE\_SCHEMA**.

This lets the Agent use the exact column names configured in the table and prevents it from inventing fields that do not exist.
{% endstep %}

{% step %}

#### Add a simple prompt

This example saves a lead and assigns a temperature based on the information available in the prompt.

{% prompt description="Save a lead and assign a temperature" icon="sparkles" openInAIProviders="true" defaultExpanded="full" %}

```
You are managing the Tiledesk Data Table "Leads".
Read the conversation transcript and extract:
- full_name
- email
- company

Then classify lead_temperature as:
- hot = clear use case and immediate interest in moving forward
- mid = relevant use case but still evaluating
- cold = general interest with no clear active project

Follow this flow:
1. Use DATATABLE_GET_TABLE_SCHEMA on the "Leads" table.
2. Use the exact column names returned by the schema.
3. Extract full_name, email, and company from the conversation transcript.
4. Determine lead_temperature from the user's intent and level of interest.
5. Use DATATABLE_UPSERT_ROWS with email as the matching condition.
6. Save:
   - full_name
   - email
   - company
   - lead_temperature
7. Use DATATABLE_QUERY_ROWS to retrieve the row by email and confirm it was saved.

Do not invent missing information.
Do not create columns that are not in the table.
```

{% endprompt %}
{% endstep %}

{% step %}

<figure><img src="https://1328774413-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVguk6y5OMn3pAaHZSiwU%2Fuploads%2FQZLIGNgmCsX9hR2K8NHS%2FScreenshot%202026-09-28%20at%2013.41.50.png?alt=media&amp;token=b2748ed7-7f37-4cde-bab8-aaa6f2004555" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### Update a lead

You can update an existing record when new information becomes available.

For example, a lead initially marked as **mid** may become **hot** after asking for a demo or confirming an active project.

{% prompt description="Update a lead temperature" icon="sparkles" openInAIProviders="true" defaultExpanded="full" %}

```
In the "Leads" table:

1. Read the conversation transcript and identify the user's email address.
2. Use DATATABLE_GET_TABLE_SCHEMA.
3. Use the exact column names returned by the schema.
4. Find the existing lead where:
   email = the email extracted from the conversation.
5. Re-evaluate the user's current level of interest based on the latest conversation.
6. Use DATATABLE_UPDATE_ROWS to update:
   lead_temperature = hot, mid, or cold
7. Use DATATABLE_QUERY_ROWS to retrieve the lead by email and confirm the update.

Do not invent missing information.
```

{% endprompt %}

### Use upsert to avoid duplicate leads

**DATATABLE\_UPSERT\_ROWS** is useful when email is used as the matching condition.

If the email already exists, the Agent updates that lead. If it does not exist, a new row is created.

{% prompt description="Upsert a lead by email" icon="sparkles" openInAIProviders="true" defaultExpanded="full" %}

```
In the "Leads" table:

1. Read the conversation transcript and extract:
   - full_name
   - email
   - company

2. Determine lead_temperature from the user's current intent:
   - hot = clear use case and immediate interest in moving forward
   - mid = relevant use case but still evaluating
   - cold = general interest with no clear active project

3. Use DATATABLE_GET_TABLE_SCHEMA.

4. Use the exact column names returned by the schema.

5. Use DATATABLE_UPSERT_ROWS with:
   condition:
   email = the email extracted from the conversation

   data:
   - full_name = extracted full name
   - email = extracted email
   - company = extracted company
   - lead_temperature = hot, mid, or cold

6. Use DATATABLE_QUERY_ROWS to retrieve the row by email and confirm the result.

Do not invent missing information.
```

{% endprompt %}

This is especially useful in conversational lead-capture flows, where the same contact may return later with new information.

### Combine Data Tables with other Tiledesk MCP tools

The Data Tables MCP becomes more useful when combined with the other Tiledesk MCP tools.

For example:

User asks a question → [Tiledesk Knowledge Base MCP](/tiledesk-mcp-tools/tiledesk-knowledge-base-mcp.md) retrieves the answer → [Tiledesk Communicator MCP](/tiledesk-mcp-tools/tiledesk-communicator-mcp.md) asks for full name, email, and company → the AI determines whether the lead is cold, mid, or hot → **Data Tables MCP** saves the lead in the Leads table.

This allows one AI Prompt to manage the full flow without creating a separate workflow action for every step.

### Example use cases

* Lead capture and qualification
* Customer request tracking
* Internal request logging
* Updating customer or contact information
* Checking existing records before taking an action
* Creating or updating records with upsert logic

#### Important: use the exact table schema

{% hint style="warning" %}
Data Tables tools work with the real schema of the selected table.

Always call **DATATABLE\_GET\_TABLE\_SCHEMA** first and use the column names returned by the tool. For example, if the schema contains `full_name`, use `full_name` rather than creating a different field such as `name`.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://guide.tiledesk.com/tiledesk-mcp-tools/tiledesk-data-tables-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.