> ## 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 Reading & Inspecting Tools

> Reference for the read-only Integrate.io MCP tools that inspect connections, packages, runs, schemas, and data quality.

The tools on this page inspect your account and its upstream systems without modifying your pipelines, connections, or schedules, so they are safe to use on production accounts. (One diagnostic, `validate_package`, records a validation and writes a workflow's script to S3, noted on its entry, but it never alters a pipeline.) Some of them (schema discovery, previews, connection tests, docs lookup) reach out to an external service on each call, so use those sparingly. Tools that create, edit, run, or schedule pipelines are documented on the [Building & Editing Packages](/etl/creating-packages-with-mcp-tools) and [Jobs & Schedules](/etl/mcp-tools-jobs-schedules) pages.

## Tool index

| Tool                                                | What it does                                                                        |
| --------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`list_connections`](#list_connections)             | Lists database and cloud-storage connections with id, name, type, and status.       |
| [`get_connection`](#get_connection)                 | One connection's non-credential shape plus suggested source/destination components. |
| [`list_workspaces`](#list_workspaces)               | Workspaces with cached package counts and recent job-activity snapshots.            |
| [`list_packages`](#list_packages)                   | Package definitions with flow type, status, last run status, and last validation.   |
| [`get_package`](#get_package)                       | One package's flow-graph summary, or the full graph with secrets redacted.          |
| [`list_clusters`](#list_clusters)                   | Compute clusters with status, node count, region, and lifecycle timestamps.         |
| [`search_all`](#search_all)                         | Free-text search across connections, packages, clusters, and workspaces.            |
| [`validate_package`](#validate_package)             | Runs structural plus script validation and returns per-component errors.            |
| [`validate_expression`](#validate_expression)       | Evaluates a single Pig expression and returns its value or error.                   |
| [`discover_schema`](#discover_schema)               | Lists tables available through a database connection.                               |
| [`discover_file_schema`](#discover_file_schema)     | Detects the columns of a delimited file on a storage or SFTP connection.            |
| [`preview_data`](#preview_data)                     | Column metadata plus a sample of rows from a database table.                        |
| [`preview_transformation`](#preview_transformation) | The output columns and rows a single component produces mid-build.                  |
| [`profile_data`](#profile_data)                     | Per-column data-quality profile over a sample of rows.                              |
| [`test_connection`](#test_connection)               | Pings a connection's upstream system to verify reachability and auth.               |
| [`ask_docs`](#ask_docs)                             | Asks the live docs a question and returns a sourced answer.                         |

***

## Account inventory

### list\_connections

**Read-only.** Lists database and cloud-storage connections in the current account. By default only active connections are returned; archived connections (for example, an OAuth connection whose token refresh failed) are hidden, the same way they are removed from the dashboard. Credentials and connection-specific properties are never returned.

<ParamField body="connection_type_filter" type="string">
  Filter by connection type. Accepts short names like `postgres` or `s3` (the same vocabulary `get_connection` uses), and the corresponding STI class names like `PostgresDatabaseConnection` for backward compatibility.
</ParamField>

<ParamField body="status" type="string" default="active">
  Which connections to list. One of `active` or `archived`.
</ParamField>

<ParamField body="limit" type="integer" default="50">
  Maximum connections to return. 1 to 200.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Number of connections to skip, for paging.
</ParamField>

<ResponseField name="connections" type="array">
  Each entry includes `id`, `name`, `type` (short form), and `status` only.
</ResponseField>

<ResponseField name="pagination" type="object">
  `offset`, `limit`, and `returned` (the count in this page).
</ResponseField>

### get\_connection

**Read-only.** Returns details for a single connection by id. Credentials, TLS certificates, and SSL keys are never returned, only a curated set of non-credential identifying fields.

<ParamField body="connection_id" type="integer" required>
  The connection id.
</ParamField>

<ParamField body="connection_type" type="string">
  Short name (for example `postgres`, `amazon_s3`) or STI class name. Only needed to disambiguate a rare id collision across the database and cloud-storage tables.
</ParamField>

<ResponseField name="id" type="integer">
  The connection id.
</ResponseField>

<ResponseField name="name" type="string">
  The connection name.
</ResponseField>

<ResponseField name="type" type="string">
  Short type identifier, for example `postgres` or `amazon_s3`.
</ResponseField>

<ResponseField name="status" type="string">
  Connection status.
</ResponseField>

<ResponseField name="owner_id" type="integer">
  The owning user id.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 last-updated timestamp.
</ResponseField>

<ResponseField name="shape" type="object">
  Non-credential identifying fields, present when set: `host`, `port`, `database`, `tunnel_type`, `local_port`, plus allowlisted properties (`schema`, `region`, `account_name`, `warehouse`, `s3_staging_dir`, `auth_method`, `ssl`).
</ResponseField>

<ResponseField name="suggested_components" type="object">
  The source and destination component types to use for this connection (for example a Snowflake connection suggests `snowflake_destination_component`, not the generic database component). Absent when there is no suggestion.
</ResponseField>

### list\_workspaces

**Read-only.** Lists workspaces in the current account. Workspaces are the recommended starting point for orienting on what work exists. The activity counts come from a cached reporting table, so they are a snapshot, not realtime.

<ParamField body="limit" type="integer" default="50">
  Maximum workspaces to return. 1 to 200.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Number of workspaces to skip, for paging.
</ParamField>

<ResponseField name="workspaces" type="array">
  Each entry includes `id`, `name`, `description`, `package_count`, `last_failed_jobs_count`, `last_completed_jobs_count`, `last_stopped_jobs_count`, `created_at`, and `updated_at`.
</ResponseField>

<ResponseField name="pagination" type="object">
  `offset`, `limit`, and `returned`.
</ResponseField>

### list\_packages

**Read-only.** Lists package definitions (ETL pipelines) in the current account. Defaults to active packages. Includes two quality signals (`last_run_status` and `last_validation`) so an agent can prefer healthy packages when picking a reference template.

<ParamField body="limit" type="integer" default="50">
  Maximum packages to return. 1 to 200.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Number of packages to skip, for paging.
</ParamField>

<ParamField body="flow_type" type="string">
  Filter by flow type. One of `dataflow` (single-stage data movement) or `workflow` (multi-stage orchestration).
</ParamField>

<ParamField body="status" type="string" default="active">
  Filter by status. One of `active` or `archived`.
</ParamField>

<ParamField body="workspace_id" type="integer">
  Restrict to packages in a single workspace.
</ParamField>

<ResponseField name="packages" type="array">
  Each entry includes `id`, `name`, `description`, `flow_type`, `status`, `workspace_id`, `version`, `version_description`, `owner_id`, `last_run_status`, `last_validation` (`{valid, status, errors_count, validated_at}` or `null`), `created_at`, and `updated_at`.
</ResponseField>

<ResponseField name="pagination" type="object">
  `offset`, `limit`, and `returned`.
</ResponseField>

### get\_package

**Read-only.** Returns a single package by id. By default you get a curated flow-graph summary (component count, edge count, component-type tally, variable count). Request the full graph to get the complete `data_flow_json`.

<ParamField body="package_id" type="integer" required>
  The package (job) id.
</ParamField>

<ParamField body="include_full_graph" type="boolean" default="false">
  Return the full `data_flow_json` blob instead of just the summary. Inline secrets (REST `?api_key=` query params, `Authorization` headers, basic-auth passwords, secrets in bash/script bodies) are masked as `[REDACTED]` server-side before the graph leaves the tool. See [Inline secret redaction in get\_package](/etl/integrateio-mcp-server#inline-secret-redaction-in-get_package).
</ParamField>

<ResponseField name="id" type="integer">
  The package id.
</ResponseField>

<ResponseField name="name" type="string">
  The package name.
</ResponseField>

<ResponseField name="flow_type" type="string">
  `dataflow` or `workflow`.
</ResponseField>

<ResponseField name="status" type="string">
  Package status.
</ResponseField>

<ResponseField name="last_run_status" type="string">
  Status of the most recent run, or `null` if never run.
</ResponseField>

<ResponseField name="last_validation" type="object">
  Most recent validation as `{valid, status, errors_count, validated_at}`, or `null` if never validated.
</ResponseField>

<ResponseField name="graph" type="object">
  Summary of the flow graph: `component_count`, `edge_count`, `variables_count`, and `component_types` (a per-type tally). `null` if the graph is missing or malformed. Also returned: `description`, `workspace_id`, `version`, `version_description`, `owner_id`, `created_at`, `updated_at`.
</ResponseField>

<ResponseField name="data_flow_json" type="object">
  The full graph. Present only when `include_full_graph` is `true`, with inline secret values redacted.
</ResponseField>

### list\_clusters

**Read-only.** Lists compute clusters (the resources package runs execute on) in the current account. Defaults to active clusters only; terminated, terminating, and pending-terminate clusters are hidden unless you pass an explicit `status`. Ordered most-recently-created first.

<ParamField body="limit" type="integer" default="50">
  Maximum clusters to return. 1 to 200.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Number of clusters to skip, for paging.
</ParamField>

<ParamField body="status" type="string">
  Filter by status (for example `available`, `idle`, `terminated`). When omitted, only active clusters are returned.
</ParamField>

<ResponseField name="clusters" type="array">
  Each entry includes `id`, `name`, `description`, `status`, `type`, `nodes`, `region`, `plan_id`, `owner_id`, `terminate_on_idle`, `time_to_idle`, and lifecycle timestamps (`launched_at`, `available_since`, `idle_since`, `terminated_at`, `created_at`, `updated_at`).
</ResponseField>

<ResponseField name="pagination" type="object">
  `offset`, `limit`, and `returned`.
</ResponseField>

### search\_all

**Read-only.** Searches across connections, packages, clusters, and workspaces using free text, so you can locate the right record without iterating through `list_*` calls. Runs (job executions) are intentionally excluded: use `list_runs` with a status filter for those.

<ParamField body="query" type="string" required>
  The free-text search query.
</ParamField>

<ParamField body="types" type="array">
  Which resource categories to search. Any of `connection`, `package`, `cluster`, `workspace`. Defaults to all four.
</ParamField>

<ParamField body="per_type_limit" type="integer" default="10">
  Maximum hits per resource type. 1 to 50.
</ParamField>

<ResponseField name="results" type="object">
  Matching records grouped by type. Connection hits carry `connection_type`; package hits carry `flow_type` and `status`; cluster hits carry `status`; workspace hits carry `description`. Every hit includes `type`, `id`, and `name`.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of hits across all searched types. Also returned: `query` and `per_type_limit`.
</ResponseField>

## Pipeline diagnostics

### validate\_package

**Read-only from the agent's point of view, but not free of side effects.** Validates a package without running it: a structural check followed by a Job Management Service (JMS) script validation, returning the per-component error list. Each call creates a `JobValidation` record and makes a network call to JMS (typically about 5 seconds, up to a few minutes for very large packages), and for workflow packages writes the script and variables to S3. It counts against the mutation rate-limit cap. Use it as a pre-flight check before running a package.

<ParamField body="package_id" type="integer" required>
  The package (job) id to validate.
</ParamField>

<ResponseField name="valid" type="boolean">
  `true` when the package validates (status `completed` with no errors).
</ResponseField>

<ResponseField name="status" type="string">
  The validation status, for example `completed` or `failed`.
</ResponseField>

<ResponseField name="errors" type="array">
  The raw validation error list.
</ResponseField>

<ResponseField name="errors_by_component" type="array">
  Errors mapped to the named component and field, with suggested fixes.
</ResponseField>

<ResponseField name="summary" type="string">
  A human-readable summary of the validation outcome.
</ResponseField>

<ResponseField name="next_steps" type="array">
  Suggested next steps to reach a valid package. Also returned: `validation_id`, `package_id`, `status_message`, `runtime_seconds`, and `validated_at`.
</ResponseField>

### validate\_expression

**Read-only.** Returns no account data. Evaluates a single Pig expression and returns its computed value or a syntax error. It has no source-column context, so expressions that reference input fields must be checked with `preview_transformation` instead.

<ParamField body="expression" type="string" required>
  The Pig expression, for example `ADDDURATION(NOW(),'P1D')` or `UPPER($name)`. Max 4000 characters.
</ParamField>

<ParamField body="variables" type="object">
  A map of `$var` name to sample value. Quote string literals, for example `{ "name": "'Al'" }`.
</ParamField>

<ResponseField name="valid" type="boolean">
  `true` with a `result`, or `false` with an `error`.
</ResponseField>

<ResponseField name="result">
  The evaluated value, when `valid` is `true`.
</ResponseField>

<ResponseField name="error" type="string">
  The syntax or validation error, when `valid` is `false`. Also returned: `expression` (echoed back).
</ResponseField>

### discover\_schema

**Read-only. Database connections only.** Lists the tables available through a database connection (Postgres, MySQL, Snowflake, and so on). Cloud-storage and SaaS connections return an error; use `discover_file_schema` for files. Each call hits the schema-importer over the network and issues a metadata query against the customer's database, so use sparingly.

<ParamField body="connection_id" type="integer" required>
  A database connection id from `list_connections`.
</ParamField>

<ParamField body="schema_name" type="string">
  Narrow to a single schema, for example `public` for Postgres.
</ParamField>

<ParamField body="limit" type="integer" default="50">
  Maximum tables to return. 1 to 200.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Number of tables to skip, for paging.
</ParamField>

<ParamField body="search" type="string">
  Substring filter applied at the schema-importer level.
</ParamField>

<ResponseField name="tables" type="array">
  The list of table names. Also returned: `connection_id`, `connection_type`, `schema_name`, `total_returned`, and `pagination`.
</ResponseField>

### discover\_file\_schema

**Read-only. Cloud-storage or SFTP connections only.** Detects the columns of a delimited file (CSV, TSV, and similar). The file-source equivalent of `discover_schema`, which handles database connections only. Each call reads a sample of the actual file over the network, so use sparingly.

<ParamField body="connection_id" type="integer" required>
  A cloud-storage or SFTP connection id.
</ParamField>

<ParamField body="path" type="string" required>
  File path on the connection, for example `/data/customers.csv`.
</ParamField>

<ParamField body="delimiter" type="string" default=",">
  Field delimiter. Use `\t` for TSV.
</ParamField>

<ParamField body="header_row" type="boolean" default="true">
  Whether the first row holds column names. When `true`, the detected field names come from that header.
</ParamField>

<ParamField body="lines" type="integer" default="20">
  Sample size the importer reads. 1 to 200.
</ParamField>

<Expandable title="Less-common options">
  <ParamField body="record_type" type="string" default="delimited">
    Record type for CSV/TSV.
  </ParamField>

  <ParamField body="record_delimiter" type="string" default="new_line">
    Row delimiter.
  </ParamField>

  <ParamField body="char_encoding" type="string" default="utf-8">
    File character encoding.
  </ParamField>

  <ParamField body="bucket" type="string" default="">
    Container or bucket. Empty is correct for SFTP, where the whole location lives in `path`.
  </ParamField>

  <ParamField body="quote" type="string">
    Optional CSV quote character.
  </ParamField>

  <ParamField body="escape" type="string">
    Optional CSV escape character.
  </ParamField>
</Expandable>

<ResponseField name="column_names" type="array">
  A flat, best-effort list of the detected column names. Use it to wire a Select.
</ResponseField>

<ResponseField name="fields" type="array">
  The importer's raw field objects, passed through unchanged, ready to copy into a source component's `schema.fields`. Also returned: `connection_id`, `connection_type`, `path`, and `field_count`.
</ResponseField>

### preview\_data

**Read-only. Database connections only.** Returns column metadata plus a small sample of rows from a database table. Each call hits the schema-importer and the customer's database, so use sparingly.

<ParamField body="connection_id" type="integer" required>
  A database connection id from `list_connections`.
</ParamField>

<ParamField body="table" type="string" required>
  Table name to sample.
</ParamField>

<ParamField body="schema_name" type="string">
  Schema the table lives in, when the database uses schemas (for example `public`).
</ParamField>

<ParamField body="row_count" type="integer" default="20">
  Rows to return. 1 to 200.
</ParamField>

<ParamField body="where_clause" type="string">
  A single SQL filter fragment. Semicolons (`;`) and comment markers (`--`, `/*`) are rejected as defense against multi-statement injection.
</ParamField>

<ResponseField name="columns" type="array">
  Column metadata for the sampled table.
</ResponseField>

<ResponseField name="rows" type="array">
  The sampled rows.
</ResponseField>

<ResponseField name="truncated" type="boolean">
  `true` when the table has more rows than were returned. Also returned: `connection_id`, `connection_type`, `schema_name`, `table`, `requested_row_count`, `where_clause`, and `row_count_returned`.
</ResponseField>

### preview\_transformation

**Read-only. Database-backed sources only (v1).** Previews what a single component produces on sample data, mid-build, without a destination. It runs the source-through-target chain on a small sample of the real source data (the same engine the dashboard "preview" button uses), so it works before a pipeline is finished, unlike `validate_package`, which needs a complete graph. Components fed by SaaS, REST, or file sources return a clear "not yet supported" error.

<ParamField body="package_id" type="integer" required>
  The package (job) id the component belongs to.
</ParamField>

<ParamField body="component_name" type="string" required>
  The inner `name` of the component whose output you want to see.
</ParamField>

<ParamField body="variables" type="object">
  Overrides for package variables during this preview run, for example for parameterized sources.
</ParamField>

<ResponseField name="component_name" type="string">
  The previewed component's name.
</ResponseField>

<ResponseField name="columns" type="array">
  The output columns, each `{ name, type }`.
</ResponseField>

<ResponseField name="rows" type="array">
  A sample of the component's output rows.
</ResponseField>

<ResponseField name="row_count" type="integer">
  Number of rows returned. A `message` is included when the preview produced no rows.
</ResponseField>

### profile\_data

**Read-only. Database connections only.** Profiles a table's columns over a sample of rows so an agent can reason about data quality before designing a pipeline. Statistics are sample-based estimates (the leading N rows returned by the database, not a random sample), not full-table figures.

<ParamField body="connection_id" type="integer" required>
  A database connection id.
</ParamField>

<ParamField body="table" type="string" required>
  Table to profile.
</ParamField>

<ParamField body="schema_name" type="string">
  Schema the table lives in.
</ParamField>

<ParamField body="columns" type="array">
  Restrict profiling to this subset of columns. Omit to profile all.
</ParamField>

<ParamField body="sample_size" type="integer" default="500">
  Rows to sample. 1 to 2000.
</ParamField>

<ParamField body="where_clause" type="string">
  A single SQL filter fragment. `;`, `--`, and `/*` are rejected.
</ParamField>

<ResponseField name="columns" type="array">
  Per column: type (inferred from sampled values), null %, approximate distinct count, min/max/mean (numeric), most common values, and quality flags (`all_null`, `high_null`, `constant`, `unique`).
</ResponseField>

<ResponseField name="sample_size_returned" type="integer">
  How many rows the sample actually contained. Also returned: `connection_id`, `schema_name`, `table`, and `note` (a reminder that the statistics are estimates).
</ResponseField>

### test\_connection

**Read-only from Integrate.io's side (no state is persisted), but it does ping the customer's upstream system.** Actively tests a connection to verify reachability and authentication, returning success or failure with the upstream error message. Failed tests can produce upstream side effects (audit log entries, rare account lockouts on bad credentials), so use it sparingly, typically once after a user reports a connection problem, not as a repeated health check.

<ParamField body="connection_id" type="integer" required>
  The connection id to test.
</ParamField>

<ParamField body="connection_type" type="string">
  Short name (for example `postgres`, `s3`) or STI class name. Disambiguates when the same integer id exists across the database and cloud-storage tables. Without it, the database row wins on collision.
</ParamField>

<ResponseField name="success" type="boolean">
  `true` if the connection was reachable and authenticated.
</ResponseField>

<ResponseField name="error_message" type="string">
  The upstream error message on failure, so the agent can suggest a specific next step (re-auth, host/port fix, and so on).
</ResponseField>

<ResponseField name="elapsed_ms" type="integer">
  How long the test took, in milliseconds. Also returned: `connection_id` and `connection_type`.
</ResponseField>

## Documentation

### ask\_docs

**Read-only.** Returns public documentation, no account data. Asks the live Integrate.io ETL & Reverse ETL documentation a question and returns an answer grounded in the docs plus source links. Consult it before guessing about component configuration, connector setup, expression functions, write modes, variables, scheduling, or clusters. Each call hits the external Mintlify API.

<ParamField body="question" type="string" required>
  Your question. Max 2000 characters.
</ParamField>

<ResponseField name="answer" type="string">
  The grounded answer.
</ResponseField>

<ResponseField name="sources" type="array">
  Supporting doc links, each `{ url, title }`.
</ResponseField>