> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ETL: MCP Use Cases and Example Prompts

> Example prompts for the Integrate.io MCP Server, from simple account questions to building, fixing, and bulk-editing pipelines.

Once your AI client is connected to the [Integrate.io MCP Server](https://www.integrate.io/docs/etl/integrateio-mcp-server.md), you can ask about, change, and run your pipelines in plain language. A common question is what to actually ask it. This page answers that with prompts you can copy, ordered from simple questions to multi-step builds and bulk changes.

Most of these come from how customers and our own team use the MCP server day to day. Swap the names in each prompt (packages, connections, tables) for your own.

> [!TIP]
>
> Prompts marked **Read** only look at your account. Prompts marked **Write** make changes, and you stay in control of each one: package edits go to a draft that only takes effect when you save it as a new version, your AI client asks you to approve each change unless you choose to auto-approve, and saved versions can be rolled back. More in [working safely with write prompts](#working-safely-with-write-prompts).

## Before you start

* Connect a client first. The [Quickstart](https://www.integrate.io/docs/etl/mcp-quickstart.md) takes about five minutes, or pick your client from [Connect a client](https://www.integrate.io/docs/etl/mcp-connect.md).
* You never give the agent a password or key. For a new connection, the agent sends you a one-time link and you type the secret in the dashboard yourself (see [Creating Connections](https://www.integrate.io/docs/etl/mcp-tools-connections.md)). Existing connections you just refer to by name.
* Use names, not ids. The agent looks up ids itself, so "the `prod-snowflake` connection" works as well as `connection_id: 42`.

## Level 1: Ask questions about your account

Start here. These prompts each use one or two read tools and return in seconds, so they are a good way to get a feel for what the agent can see.

**Get an overview** (Read)

```text Prompt wrap theme={null}
List the workspaces in my Integrate.io account and summarize the health of each one.
```

**Find recent failures** (Read)

```text Prompt wrap theme={null}
Show me every job that failed in the last 24 hours. Group them by package and summarize the most common errors.
```

**Explain a failure** (Read)

```text Prompt wrap theme={null}
My Salesforce to Snowflake package failed this morning. What broke, and how do I fix it?
```

> [accordion] Example response
>
> Based on a real job log, with names changed:
>
> Run 4815162 of **salesforce\_opportunities\_to\_snowflake** failed at 06:07 UTC, about 20 seconds in. The dashboard only shows "Package failed to execute", so here is what the log says.
>
> **What broke:** the Snowflake destination couldn't write to its table. Snowflake returned:
>
> `Table 'OPPORTUNITY' already exists, but current role has no privileges on it.`
>
> The table exists, but it's owned by a different role than the one your Snowflake connection uses. That usually happens when someone recreates the table by hand or from another tool. The Salesforce side read fine, and the package itself is valid.
>
> **How to fix it:** ask your Snowflake admin to give the connection's role access to the table, for example:
>
> `GRANT ALL PRIVILEGES ON TABLE ANALYTICS.SALESFORCE.OPPORTUNITY TO ROLE INTEGRATEIO_ROLE;`
>
> Then re-run the package. No changes to the package are needed. Want me to retry the run once the grant is in place?

**Check record counts** (Read)

```text Prompt wrap theme={null}
How many records did the last run of the orders_daily package read from each source and write to each destination?
```

**Review schedules** (Read)

```text Prompt wrap theme={null}
Which schedules are disabled, and which enabled schedules run more often than once an hour?
```

**Look at source data** (Read)

```text Prompt wrap theme={null}
What tables are on the production-postgres connection? Show me 20 rows from the orders table where amount is over 1000.
```

**Ask the docs** (Read)

```text Prompt wrap theme={null}
How does the Snowflake destination handle merge keys? Answer from the Integrate.io docs.
```

| Prompt | Tools the agent typically calls |
| - | - |
| Overview | `list_workspaces` |
| Failures | `list_runs`, `explain_job_failure` |
| Explain a failure | `search_all`, `list_runs`, `explain_job_failure` |
| Record counts | `list_runs`, `get_run_summary` |
| Schedules | `list_schedules` |
| Source data | `discover_schema`, `preview_data` |
| Docs | `ask_docs` |

## Level 2: Document and audit your pipelines

The agent can read the full definition of every package, so it can describe your pipelines in plain language and cross-reference them. This is one of the most common first uses: getting a clear map of what you have before changing anything.

**Map everything that touches one system** (Read)

```text Prompt wrap theme={null}
Find every package that reads from or writes to HubSpot. For each one, list the objects it touches, the destination tables, the schedule it runs on, and when it last succeeded. Put it in a table.
```

> [accordion] Example response
>
> From a demo account, lightly trimmed:
>
> I found 6 packages that touch HubSpot. None of them is on a schedule.
>
> | Package | Direction | Objects / tables | Last run | Health |
> | - | - | - | - | - |
> | Hubspot Contact Lists to Redshift | HubSpot → Redshift | Contact lists and list members into two Redshift tables | Never run | Never validated |
> | SFTP to HubSpot CSV Import | SFTP → HubSpot | CSV files, filtered, into HubSpot | Stopped | Validates |
> | SFTP to HubSpot (×2) | SFTP → HubSpot | CSV files into HubSpot (one copy is empty) | Never run | Not validated |
> | HubSpot Contacts to Salesforce (×2) | HubSpot → Salesforce | Contacts to the Salesforce Contact object | Never run | Latest validation failed (1 error) |
>
> Things to look at: there are two copies each of "SFTP to HubSpot" and "HubSpot Contacts to Salesforce", and one "SFTP to HubSpot" has no components at all, so it's safe to archive. Nothing here has completed a run, so if HubSpot data is landing somewhere today, it isn't coming from these packages. Want me to compare the duplicates?

**Write documentation for a package** (Read)

```text Prompt wrap theme={null}
Explain what the customer_360_merge package does, step by step, for someone who has never opened it. Cover the sources, every transformation and filter, the destination, and how it is scheduled.
```

**Document the whole account** (Read)

```text Prompt wrap theme={null}
Build a reference document of all packages that are on an active schedule. For each: purpose, sources, destinations, key transformations, schedule, and recent run health. Flag any package that hasn't run in 30 days.
```

**Trace where a table comes from** (Read)

```text Prompt wrap theme={null}
Which packages write to the analytics.dim_customer table in Snowflake? Trace each one back to its original source and tell me if two packages could overwrite each other.
```

**Find clean-up candidates** (Read)

```text Prompt wrap theme={null}
List packages that are not on any schedule and have not run in the last 90 days, and connections that no package uses. I want to decide what to archive.
```

**Profile data before you build** (Read)

```text Prompt wrap theme={null}
Profile the customers table on the production-postgres connection. Which columns have a lot of nulls, which look like unique keys, and is anything constant?
```

> [!TIP]
>
> Ask for the output in the format you need: a table, a Markdown doc for your wiki, or a CSV. In Claude and ChatGPT you can then turn it into a spreadsheet or document directly.

## Level 3: Troubleshoot and fix

Here the agent moves from reading to changing things. It diagnoses a problem with read tools, then proposes an edit. Edits land in your **draft** of the package first. Nothing runs differently until the draft is saved as a new version.

**Diagnose, then propose a fix** (Read, then Write)

```text Prompt wrap theme={null}
Run 4815162 failed. Explain why. If the fix is a change to the package, show me exactly what you would change and wait for my go-ahead before editing anything.
```

**Fix an expression** (Write)

```text Prompt wrap theme={null}
In the orders_daily package, the order_total field in the clean_orders Select is failing on null quantities. Rewrite the expression so nulls are treated as 0, check it with validate_expression first, then update the component and validate the package.
```

**Save and re-run** (Write)

```text Prompt wrap theme={null}
The draft looks good. Save it as a new version with the note "Handle null quantities", then retry the failed run and tell me when it finishes and how many records it wrote.
```

**Morning health check** (Read, optional Write)

```text Prompt wrap theme={null}
Check every run from the last 12 hours. For each failure, explain the cause in one line and say whether it looks like a data issue, a credential or connection issue, or a package bug. Don't retry anything yet, just give me the list.
```

**Test a connection** (Read)

```text Prompt wrap theme={null}
Test the prod-snowflake connection. If it fails, tell me why and what I should check.
```

**Undo a change** (Write)

```text Prompt wrap theme={null}
Show me the version history of the orders_daily package and roll it back to the version before today's edit.
```

## Level 4: Build new pipelines

The agent can build a complete source-to-destination package from a description. For a straight "load X into Y", it does this in a single call and validates the result. For anything with filters, joins, or several sources, it builds component by component.

**Set up a connection** (Write)

```text Prompt wrap theme={null}
I need a PostgreSQL connection to our reporting database at reporting.internal.example.com, database analytics, user etl_reader. Send me a connection link and I'll enter the password myself.
```

**One-step load** (Write)

```text Prompt wrap theme={null}
Build a package that loads the Salesforce Opportunity object into Snowflake, table SALESFORCE.OPPORTUNITY on the prod-snowflake connection. Merge on Id. Add a column called loaded_at with the current timestamp. Use the salesforce-prod connection for the source.
```

**Load files with lineage** (Write)

```text Prompt wrap theme={null}
Build a package that reads the CSV files under /exports/orders/ on the partner-sftp connection and loads them into Snowflake table RAW.ORDERS. Add a column with the source file path and one with the file's modified time.
```

**Start from an existing package** (Write)

```text Prompt wrap theme={null}
Clone the stripe_charges_to_snowflake package into the Staging workspace as stripe_refunds_to_snowflake. Then change the source to the refunds endpoint and the destination table to RAW.STRIPE_REFUNDS. Validate it and show me the differences from the original.
```

**Add a transformation** (Write)

```text Prompt wrap theme={null}
In the customer_sync package, add a Filter after the source that drops rows where email is empty or ends in @example.com, and wire it in before the Select. Validate the package and preview the filter's output.
```

**Add a package variable** (Write)

```text Prompt wrap theme={null}
Add a variable called start_date to the orders_daily package with the default value 2026-01-01, so I can change the date for each run.
```

**Run it and schedule it** (Write)

```text Prompt wrap theme={null}
Save the draft of customer_sync, run it once on the available cluster, and if it succeeds, create a schedule that runs it every day at 06:00 UTC. Leave the schedule disabled so I can review it.
```

> [!TIP]
>
> New schedules created through the MCP server are disabled by default. Ask the agent to enable one only after you have checked it.

**Turn on a schedule** (Write)

```text Prompt wrap theme={null}
Turn on the customer_sync schedule and tell me when it will run next.
```

**Change when a schedule runs** (Write)

```text Prompt wrap theme={null}
Change the customer_sync schedule to run every day at 04:00 UTC instead of 06:00.
```

## Level 5: Change many pipelines at once

This is where the MCP server saves the most time. Work that would take days of clicking through the designer becomes a prompt plus a review. One customer used it to regenerate a large set of packages and estimated it cut about three months of manual work down to three days.

These prompts work best in a client that can run long tasks, such as Claude Code, Claude Desktop, or Cursor.

**Apply one change everywhere** (Write)

```text Prompt wrap theme={null}
We renamed the column cust_id to customer_id in our source database. Find every package that reads cust_id, list them, and for each one show the change you would make. After I confirm, update them one at a time, validate each, and give me a summary of which ones are ready to save.
```

**Roll out a template** (Write)

```text Prompt wrap theme={null}
I updated the shopify_orders_template package. Compare it to the 12 store-specific Shopify packages and update each one to match the template's transformations, keeping each package's own connection and destination table. Validate everything and report back before saving.
```

**Bulk schedule changes** (Write)

```text Prompt wrap theme={null}
Find every package in the Marketing workspace that runs on an hourly schedule. Create one new schedule that runs all of them every 4 hours and leave it disabled. Then list the hourly schedules I should disable once I switch over. Show me the plan first.
```

**Rebuild pipelines from another tool** (Write)

```text Prompt wrap theme={null}
Here is an export of a pipeline from our old ETL tool [paste or attach]. Recreate it as an Integrate.io package using the salesforce-prod and prod-snowflake connections. Keep the same filters and business rules. List anything you could not translate so I can check it by hand.
```

**Hand off a whole project** (Write)

```text Prompt wrap theme={null}
I need daily loads of Account, Contact, Opportunity, and Lead from Salesforce into the SALESFORCE schema in Snowflake, merging on Id. Build one package per object, validate each, run them once, and then put all four on one schedule at 05:00 UTC, disabled. Give me a summary table of package ids, row counts from the test runs, and anything that needs my attention.
```

> [!NOTE]
>
> Teams that use the MCP server heavily tend to do the routine work (cloning, troubleshooting, bulk edits) through the agent and then open the dashboard for the last mile: a final review of the canvas, or a tricky component. Knowing the platform well makes it much easier to check what the agent did.

## Writing better prompts

* **Be specific about names.** Name the package, connection, table, or workspace. The agent will search if you don't, but it may pick the wrong match.
* **Ask for a plan first on any write.** "Show me what you would change and wait for my go-ahead" is the single most useful phrase for write prompts.
* **Ask it to validate.** Mention `validate_package` or "validate before saving" and the agent will catch wiring and expression errors before anything runs.
* **Say what output you want.** A table, a doc, a list of ids, or a yes/no answer.
* **Never paste credentials into the chat.** No tool returns credentials, and new connections are finished through a one-time dashboard link where you enter the secret yourself. Point the agent at existing connections by name.

## Working safely with write prompts

* **Keep write tools on approval in your client.** Claude, Cursor, and most other clients ask before each tool call unless you choose "Always allow". Allowing the read tools saves clicks, but leave the write tools set to ask, so you approve every change before it happens.
* **Edits go to a draft first.** Component, edge, and variable edits change your draft only. Runs and schedules keep using the saved version until the draft is saved with `save_package_version`. Ask the agent to show you the draft before it saves.
* **Use dry runs.** Many write tools, including `clone_package`, `update_package_components`, `save_package_version`, `create_schedule`, `update_schedule`, and `run_package`, accept `dry_run`. Ask "do a dry run first" to see what would change without changing it.
* **Everything is versioned.** Saved changes appear in the package version history and the account audit log, and `revert_package` can roll a package back. Unsaved drafts that are discarded cannot be recovered.
* **Clusters cost money.** `create_cluster` provisions billed infrastructure. If you don't want the agent to create one, say so in the prompt.
* **Control access with permissions.** The agent can only do what the signed-in user can do. Give people who only need to look a read-only role.

## Related

> [card] [Reading & Inspecting tools](https://www.integrate.io/docs/etl/mcp-tools-reading.md)

> [card] [Building & Editing Packages](https://www.integrate.io/docs/etl/creating-packages-with-mcp-tools.md)

> [card] [Jobs & Schedules](https://www.integrate.io/docs/etl/mcp-tools-jobs-schedules.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.