Skip to content

@W-22350774: Add Tableau Prep flows tools (list-flows, get-flow) #344

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
showmethecold wants to merge 1 commit into
base: main
Choose a base branch
from
Open

@W-22350774: Add Tableau Prep flows tools (list-flows, get-flow) #344

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/docs/configuration/mcp-config/env-vars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -454,6 +454,21 @@ Enables product telemetry for tool usage tracking.

<hr />

## `FLOW_TOOLS_ENABLED`

Controls whether the Tableau Prep flow tools are registered.

- Default: `false`
- Set to `true` to enable the Tableau Prep flow tools:
- [`list-flows`](../../tools/flows/list-flows.md)
- [`get-flow`](../../tools/flows/get-flow.md)
- Only the exact value `true` enables them; any other value (or leaving it unset) keeps them
disabled.
- When enabled, individual flow tools can still be excluded via
[`EXCLUDE_TOOLS`](#exclude_tools) (e.g. `EXCLUDE_TOOLS=flow`).

<hr />

## `ADMIN_TOOLS_ENABLED`

Enables admin-only tools that require site administrator permissions.
Expand Down
40 changes: 28 additions & 12 deletions docs/docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,16 @@ sidebar_position: 1

# Introduction

Tableau's official MCP Server. Helping *agents* see and understand data.

Tableau's official MCP Server. Helping _agents_ see and understand data.

[Tableau MCP](https://github.com/tableau/tableau-mcp) is an open source GitHub project that uses the
[Model Context Protocol](https://modelcontextprotocol.io/introduction) standard for simplifying
agent-to-Tableau communication, enabling users to bring their Tableau data into AI tools. This MCP server can be used with any Tableau edition on Cloud or Server, though specific tools may be gated by SKU.
agent-to-Tableau communication, enabling users to bring their Tableau data into AI tools. This MCP
server can be used with any Tableau edition on Cloud or Server, though specific tools may be gated
by SKU.

Tableau MCP is also a managed service on every Tableau Cloud pod, and it is accessible over the url: `https://mcp.tableau.com`. See [Hosted Tableau MCP](hosted-tableau-mcp) for more details.
Tableau MCP is also a managed service on every Tableau Cloud pod, and it is accessible over the url:
`https://mcp.tableau.com`. See [Hosted Tableau MCP](hosted-tableau-mcp) for more details.

Follow along and share ideas with the Tableau MCP team by creating issues or discussions on the
repository. You can also join the [Tableau Developer Platform](https://www.tableau.com/developer)
Expand All @@ -20,16 +22,21 @@ Slack channel in the Tableau #DataDev workspace.

## Use Cases

- Chat with your data: Reuse your trusted, curated data models to answer ad-hoc questions that are grounded on your pre-built data semantics and metadata.
- Find insights from pre-built data artifacts: Enable agents to query your published workbooks and extract data, images, custom views and more.
- Discover and analyze Pulse metrics: Bring 100% accuracy and deterministic AI to any agent by using Pulse metric definitions and the Pulse insights engine.
- Chat with your data: Reuse your trusted, curated data models to answer ad-hoc questions that are
grounded on your pre-built data semantics and metadata.
- Find insights from pre-built data artifacts: Enable agents to query your published workbooks and
extract data, images, custom views and more.
- Discover and analyze Pulse metrics: Bring 100% accuracy and deterministic AI to any agent by using
Pulse metric definitions and the Pulse insights engine.
- Manage and administer your Tableau environment.

### Coming soon!
### Coming soon!

- Prepare your data and manage prep flows.
- Pre-built skills that use the Tableau MCP toolset.
- Collaboratively or autonomously build Tableau workbooks: new tools and skills allow local coding agents to directly work with and take action on Tableau Desktop. Drag and drop your way to insights or let an agent do it for you!

- Collaboratively or autonomously build Tableau workbooks: new tools and skills allow local coding
agents to directly work with and take action on Tableau Desktop. Drag and drop your way to
insights or let an agent do it for you!

## Tool List

Expand All @@ -40,8 +47,10 @@ Slack channel in the Tableau #DataDev workspace.
| [list-projects](tools/projects/list-projects.md) | Retrieves a list of projects from a specified Tableau site ([REST API][list-projects]) | All SKUs |
| [list-views](tools/views/list-views.md) | Retrieves a list of views from a specified Tableau site ([REST API][list-views]) | All SKUs |
| [list-custom-views](tools/views/list-custom-views.md) | Retrieves a list of custom views for a specified Tableau workbook ([REST API][list-custom-views]) | All SKUs |
| [list-flows](tools/flows/list-flows.md) | Retrieves a list of Tableau Prep flows from a specified Tableau site ([REST API][list-flows]) | All SKUs |
| [get-datasource-metadata](tools/data-qna/get-datasource-metadata.md) | Fetches datasource metadata including table relationships, datasource and field descriptions, field roles and types, calculation strings, and parameters for the specified datasource ([Metadata API][meta] & [VDS API][vds]) | All SKUs\* |
| [get-workbook](tools/workbooks/get-workbook.md) | Retrieves information about a workbook for a specified workbook on a Tableau site ([REST API][get-workbook]) | All SKUs |
| [get-flow](tools/flows/get-flow.md) | Retrieves information on a Tableau Prep flow including output steps and recent runs ([REST API][get-flow]) | All SKUs |
| [delete-workbook](tools/workbooks/delete-workbook.md) | Admin-only. Two-phase (preview/confirm) delete of a workbook; recoverable via recycle bin ([REST API][delete-workbook]) | All SKUs |
| [delete-datasource](tools/data-qna/delete-datasource.md) | Admin-only. Two-phase (preview/confirm) delete of a published data source; warns on dependent workbooks/flows; recoverable via recycle bin ([REST API][delete-datasource]) | All SKUs |
| [get-view-data](tools/views/get-view-data.md) | Retrieves data in CSV format for the specified view in a Tableau workbook. *Note: the get-view-data api currently has a limitation that when used on a dashboard sheet type, it will only return data for the first worksheet in the dashboard. This will be fixed in the 26.3 fall release.* ([REST API][get-view-data]) | All SKUs |
Expand All @@ -66,7 +75,9 @@ Slack channel in the Tableau #DataDev workspace.
| [query-admin-insights-job-performance](tools/admin-insights/query-admin-insights-job-performance.md) | Admin-only. Issues a VDS query against the Admin Insights `Job Performance` datasource ([VDS API][vds]) | All SKUs |
| [get-stale-content-report](tools/admin-insights/get-stale-content-report.md) | Admin-only. Deterministic stale-content report from `Site Content` ([VDS API][vds]) | All SKUs |

\* The `get-datasource-metadata` tool relies on both the VizQL Data Service and the Metadata API to get rich metadata about a data source. Only sites with Data Management entitlements will be able to execute the Metadata API calls, though the tool will remain functional without it.
\* The `get-datasource-metadata` tool relies on both the VizQL Data Service and the Metadata API to
get rich metadata about a data source. Only sites with Data Management entitlements will be able to
execute the Metadata API calls, though the tool will remain functional without it.

[query]:
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#query_data_sources
Expand All @@ -78,8 +89,12 @@ Slack channel in the Tableau #DataDev workspace.
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_views_for_site
[list-custom-views]:
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#list_custom_views
[list-flows]:
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flows_for_site
[get-workbook]:
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_workbook
[get-flow]:
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow
[delete-workbook]:
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#delete_workbook
[delete-datasource]:
Expand Down Expand Up @@ -108,7 +123,8 @@ Slack channel in the Tableau #DataDev workspace.

## Prompt List

Prompts orchestrate multiple tools into a guided admin workflow. They are gated behind the `ADMIN_TOOLS_ENABLED` site setting.
Prompts orchestrate multiple tools into a guided admin workflow. They are gated behind the
`ADMIN_TOOLS_ENABLED` site setting.

| **Prompt** | **Description** |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
Expand Down
8 changes: 8 additions & 0 deletions docs/docs/tools/flows/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Flows",
"position": 6,
"link": {
"type": "generated-index",
"description": "Tools for retrieving information about Tableau Prep flows."
}
}
224 changes: 224 additions & 0 deletions docs/docs/tools/flows/get-flow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,224 @@
---
sidebar_position: 2
---

# Get Flow

Retrieves detailed information about a specific Tableau Prep flow, including its output steps and
optionally its input data connections and recent flow runs.

## APIs called

- [Query Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow)
- [Query Flow Connections](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow_connections)
(optional)
- [Get Flow Runs](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#get_flow_runs)
(optional, requires Tableau REST API >= 3.10)

## Required Tableau API scopes

When the MCP server authenticates with OAuth (connected-app JWT), this tool requests at most:

- `tableau:flows:read` (always)
- `tableau:mcp_site_settings:read` (always)
- `tableau:flow_connections:read` (only when `includeConnections: true`)
- `tableau:flow_runs:read` (only when `includeFlowRuns: true`)

The sidecar scopes are requested **only** for the sidecars you ask for, so a metadata-only call
(`includeConnections: false, includeFlowRuns: false`) succeeds against a connected app that grants
just `tableau:flows:read` (plus the always-on site-settings scope). Flows use the dedicated
`tableau:flows:read` scope, not the `tableau:content:read` scope used by workbooks, data sources,
and views. See [OAuth configuration](../../configuration/mcp-config/oauth.md) for details.

## Required arguments

### `flowId`

The ID of the flow, potentially retrieved by the [List Flows](list-flows.md) tool.

Example: `d00700fe-28a0-4ece-a7af-5543ddf38a82`

## Optional arguments

### `includeConnections`

When `true` (default), additionally returns the input data connections for the flow.

If the connections sidecar call fails (e.g. permissions error), the tool still returns the flow
metadata and emits a warning under `mcp.warnings` instead of failing the entire call.

When `false`, the tool also **narrows the Tableau API scopes requested at JWT sign-in** — it does
not request `tableau:flow_connections:read`. This means a metadata-only call succeeds against a
Connected App that grants only `tableau:flows:read`, even when the operator chose not to grant the
optional sidecar scopes. If both `includeConnections` and `includeFlowRuns` are `false`, the JWT
requests only `tableau:flows:read` plus the always-on site-settings scope.

### `includeFlowRuns`

When `true` (default), additionally returns the most recent flow runs for this flow.

Requires Tableau REST API version 3.10 (Tableau Server 2020.4) or later. On older servers, this
sidecar call is skipped and a `VERSION_GATE_SKIPPED` warning is emitted under `mcp.warnings`.

When `false`, the tool also **narrows the Tableau API scopes requested at JWT sign-in** — it does
not request `tableau:flow_runs:read`. See `includeConnections` above for the metadata-only
deployment story.

### `flowRunLimit`

The maximum number of recent flow runs to return when `includeFlowRuns` is `true`. Must be between 1
and 100. Default: `10`. Runs are sorted by `startedAt` descending (newest first).

When the flow has more historical runs than this limit, the tool returns the most-recent slice and
emits a [`FLOW_RUNS_TRUNCATED`](#run-history-truncation-flow_runs_truncated) warning under
`mcp.warnings`. **There is no other signal in the response that distinguishes a truncated history
from a complete one** — always inspect `mcp.warnings` before reporting "complete history" to the
user.

## Response-size guidance

By default this tool returns metadata + output steps + all connections + the 10 most-recent runs.
Each sidecar adds payload, so the tool description steers the LLM toward the narrowest call that
answers the user's question:

| Question shape | Recommended arguments |
| ------------------------------------------- | --------------------------------------------------- |
| "What is this flow?" (just metadata) | `includeConnections: false, includeFlowRuns: false` |
| "What does this flow read from?" | `includeFlowRuns: false` (keep `connections`) |
| "Did the latest run succeed?" (status only) | `flowRunLimit: 1` (or 3) |
| "Show me the run history" | `flowRunLimit: <n>` up to 100 |

When in doubt, prefer the lower limit — the LLM can always re-call with a higher limit if the first
response is insufficient.

## Partial failure (`mcp.warnings`)

The primary
[Query Flow](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow)
call is atomic; if it fails, the tool returns an error.

The optional `connections` and `flowRuns` sidecars are best-effort. If either of them fails (for
example, the user lacks permission, the server is too old, or the request times out) the tool will
still return the flow's primary metadata and surface a structured warning instead of failing the
whole tool call. The tool can emit three warning types:

### `SIDECAR_FETCH_FAILED`

```json
{
"type": "SIDECAR_FETCH_FAILED",
"severity": "WARNING",
"message": "Failed to fetch connections: HTTP 403 Forbidden",
"affectedField": "connections",
"httpStatus": "403"
}
```

### `VERSION_GATE_SKIPPED`

Emitted when `includeFlowRuns: true` but the Tableau server is older than REST API 3.10 (Tableau
Server 2020.4):

```json
{
"type": "VERSION_GATE_SKIPPED",
"severity": "WARNING",
"message": "Flow runs require Tableau REST API 3.10 or later; this server is older.",
"affectedField": "flowRuns"
}
```

### Run-history truncation (`FLOW_RUNS_TRUNCATED`)

Emitted when the flow has more runs than `flowRunLimit`. The `flowRuns` array contains the
most-recent slice; older runs exist but are NOT in the response.

```json
{
"type": "FLOW_RUNS_TRUNCATED",
"severity": "WARNING",
"message": "Returned the 10 most-recent flow runs (sorted startedAt desc). The flow has additional historical runs not included in this response. To see more runs: 1. Re-call this tool with a higher `flowRunLimit` (max 100). 2. For deeper history (more than 100 runs) use the Tableau Flow Runs REST API directly with `filter=flowId:eq:<id>` and `pageNumber` pagination, or with a date-range filter (e.g. `startedAt:gt:<iso-timestamp>`).",
"affectedField": "flowRuns",
"returnedCount": 10
}
```

**Why this warning exists.** The Tableau Flow Runs endpoint (`GET /sites/{site}/flows/runs`) does
not return a `pagination` block, so the tool cannot read `totalAvailable` to know whether the
response was truncated. Instead it uses the **"+1 probe"** technique: request `flowRunLimit + 1`
rows in a single call; if more than `flowRunLimit` come back, the array was truncated and this
warning is emitted (verified live against Tableau REST 3.30).

**Recovery actions.** When you see this warning:

1. If the user wants more recent context, re-call with a higher `flowRunLimit` (up to 100).
2. If the user wants deeper history (more than 100 runs, or a specific date range), this tool cannot
satisfy it in v0. Recommend the user query the Tableau Flow Runs REST API directly with
`filter=flowId:eq:<id>` and `pageNumber` pagination, or with a date-range filter such as
`startedAt:gt:2025-01-01T00:00:00Z`.

**Anti-patterns.** Do NOT confidently report a partial run history (e.g. "this flow has run 10
times") when this warning is present — the response is a window onto a longer history, not the
complete record. Daily-running production flows can easily accumulate hundreds of runs per year.

## Limitations

A few things this tool deliberately does **not** expose in the current version:

- **No error details for `Failed` flow runs.** The `flowRuns[*].status` field is available (e.g.
`Success`, `Failed`, `Cancelled`), but the underlying job error message is not surfaced by the
public Tableau REST API and is therefore not exposed here. To investigate a failure, inspect the
run in the Tableau Server / Cloud UI.
- **No per-output-step run details.** The `flowRuns` field reflects ad-hoc runs returned by the
public REST API; per-output-step success/failure breakdowns and timings are not included.
- **No exact total-run count.** Tableau's Flow Runs endpoint does not expose a `totalAvailable`
field, so the tool cannot report exactly how many runs exist beyond what was returned — only
whether more do, via the [`FLOW_RUNS_TRUNCATED`](#run-history-truncation-flow_runs_truncated)
warning. For deeper history queries, see the recovery actions on that warning.

## Example result

```json
{
"id": "d00700fe-28a0-4ece-a7af-5543ddf38a82",
"name": "Sales Cleanup",
"description": "Cleans up the daily sales feed",
"webpageUrl": "https://10ax.online.tableau.com/#/site/mcp-test/flows/3",
"fileType": "tflx",
"createdAt": "2024-11-06T04:57:55Z",
"updatedAt": "2024-11-06T21:31:00Z",
"project": {
"id": "6f8a2966-e173-11e8-ae74-ffd84c19d7f3",
"name": "Default",
"description": "The default project that was automatically created by Tableau."
},
"owner": {
"id": "711e59cf-d1c0-446e-be48-3673ae067f7b",
"name": "jane.doe@example.com",
"fullName": "Jane Doe",
"email": "jane.doe@example.com",
"siteRole": "Creator"
},
"tags": { "tag": [{ "label": "sales" }] },
"outputSteps": [{ "id": "5e4c9a74-d29a-4f62-baa5-97c443440dfc", "name": "CoffeeChainOutputCSV" }],
"connections": [
{
"id": "5fd1c1db-572f-4ebd-94e7-a09e212bc147",
"type": "sqlserver",
"serverAddress": "mySQLServer",
"userName": "analyst",
"embedPassword": true
}
],
"flowRuns": [
{
"id": "a1a1a1a1-1111-1111-1111-111111111111",
"flowId": "d00700fe-28a0-4ece-a7af-5543ddf38a82",
"status": "Success",
"startedAt": "2025-04-01T10:00:00Z",
"completedAt": "2025-04-01T10:05:00Z",
"progress": 100
}
]
}
```
Loading
Loading