> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-for-data-analysis.md). # MCP - For data analysis The Smartico Model Context Protocol (MCP) Server provides dedicated analytics tools that enable external AI assistants—such as Claude, ChatGPT, and automated analytical scripts—to explore the Data Warehouse schema and execute read-only queries. Instead of manually writing complex queries across unfamiliar table structures, your assistant can discover relevant data warehouse tables in natural language, inspect column definitions and join keys, validate query costs with dry runs, and extract clean datasets formatted as CSV. These tools allow business operators, CRM managers, and BI analysts to move seamlessly from a plain-language question to rich analytical deliverables, including interactive dashboards in Claude Artifacts, collaborative reports in ChatGPT Canvas, and ready-to-use CSV exports. *** ## Data Analysis Tools Overview The MCP Server exposes two specialized analytical tools designed to separate schema discovery from query execution. This two-phase architecture ensures that AI assistants understand your account's schema and join paths before running queries. | Tool Name | Tool Invocation | Purpose | Primary Parameters | Result Format | Token & Cost Impact | | --------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | **Schema Discovery** (`get_analytics_bi_structure`) | `get_analytics_bi_structure` | Discovers analytics tables, column definitions, data types, and join relationships. | `query` (topic search), `tables` (detailed schema lookup), `label_id` (optional) | Structured map of matching tables, columns, suggested join definitions, and practical query examples | **Free** (cached schema inspection; consumes no AI data-scan tokens) | | **SQL Execution** (`exec_sql`) | `exec_sql` | Executes a single read-only BigQuery Standard SQL query starting with `SELECT` or `WITH`. | `sql` (query string), row limit (1–1,000, default 100), `dry_run` (boolean), `as_file` (boolean), `label_id` (optional) | CSV formatted data, column types, record count, truncation indicator, and tokens used; with `as_file`, also a link to the whole result as a file | Consumes monthly AI tokens based on processed data volume; **Free** when `dry_run: true` | {% hint style="info" %} **Access Profile Requirements:** The `get_analytics_bi_structure` and `exec_sql` tools require an access profile that includes Data Warehouse permissions, such as **MCP Analyst** or **MCP Full access**. Connections using **MCP Viewer** or **MCP Editor** will receive a permission refusal when attempting to call these tools. For detailed permission breakdowns, see [MCP Access Profiles](/welcome/technical-guides/mcp-server/mcp-access-profiles.md). {% endhint %} *** ## Start with Golden Queries Before you write SQL, look for a golden query: a fixed data question that Smartico wrote and tested, such as who entered a campaign, who received, opened or clicked a message, or which bonuses were issued. Its definitions are fixed, so the numbers are the same in every run. | Tool | What it does | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `find_golden_queries` | Searches the golden queries by `keywords` (a few English words); without keywords, lists them all. Returns cards with the key, what the query answers, and its params with examples — never the SQL. Read-only. | | `run_golden_query` | Runs a golden query by its `key` with the values in `params`. The answer is like `exec_sql`'s: the columns, the rows as CSV, the row count, and the tokens used. Takes `dry_run`, `max_rows`, `force`, and `as_file` like `exec_sql` (`as_file` only for golden queries that read the data warehouse). Consumes monthly AI tokens. | | `get_golden_query_sql` | Returns the SQL of a golden query, with your values in when you pass `params`, as a start for your own `exec_sql` query. Runs nothing. | Some golden queries read live state, such as a tournament's current standing, from the Back-Office database instead of the data warehouse. `find_golden_queries` and `run_golden_query` are in the **MCP Full access**, **MCP Editor**, and **MCP Analyst** profiles, so an Editor can run them without `exec_sql`. `get_golden_query_sql` comes with `exec_sql`. For the current list of golden queries and what each one answers, see [MCP - Golden queries](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-golden-queries). *** ## Tool 1: Schema Discovery (`get_analytics_bi_structure`) The `get_analytics_bi_structure` tool provides guided discovery of your account's Data Warehouse. It operates in three distinct modes depending on the parameters provided. ### Discovery Modes 1. **Catalog Overview (No parameters):** Calling the tool without arguments returns a high-level map of your account's Data Warehouse dataset. It lists all reference and dimensional tables with concise descriptions, alongside a list of all transactional event tables. 2. **Topic Search (`query`):** Pass a natural-language description of your analysis (in English), such as `"player deposits by brand"` or `"bonus turnover and wagering"`. The tool searches and ranks matching tables, returning up to 8 relevant tables with descriptions, column lists (up to 40 columns each), and suggested join relationships. 3. **Full Table Definition (`tables`):** Pass an array of 1 to 5 exact table names discovered in the search step. The tool returns complete schema details: exact column data types, field descriptions, join keys with recommended join clauses, and practical query examples. ### Calling `get_analytics_bi_structure` with cURL #### Mode A: Search by Topic ```bash curl -X POST https:///mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-mcp-mode: json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_analytics_bi_structure", "arguments": { "query": "first time deposits and acquisition marketing channels" } } }' ``` #### Mode B: Retrieve Full Table Schema ```bash curl -X POST https:///mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-mcp-mode: json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_analytics_bi_structure", "arguments": { "tables": ["j_user_no_enums"] } } }' ``` *** ## Tool 2: Analytics SQL Execution (`exec_sql`) The `exec_sql` tool runs a single read-only BigQuery Standard SQL statement against your account's Data Warehouse dataset. ### Execution Parameters * `sql` (string, required): A single BigQuery Standard SQL statement starting with `SELECT` or `WITH`. Multiple statements separated by semicolons are strictly rejected. Write every table with its dataset, for example `dwh_ext_.j_user_no_enums`. * `max_rows` (number, optional): Maximum number of rows to return (between 1 and 1,000; defaults to 100). If the query matches more rows than requested, the tool caps the output and sets a truncation indicator. With `as_file: true`, it sets only the rows shown in the answer (default 20). * `as_file` (boolean, optional): Saves the whole result, up to 500,000 rows, as a file and returns a download link. Use it only from a client that can download and process a file. See [Large Results as a File](#large-results-as-a-file). * `force` (boolean, optional): Runs a query that is over the single-query limit of 300,000 tokens, up to 2,000,000 tokens. Send it only after the limit was answered, and only when a narrower query will not do: the tokens come from the monthly AI allocation. * `dry_run` (boolean, optional): When set to `true`, validates query syntax, checks column existence against the active schema, and reports how many tokens the query would use (`estimated_tokens`) without executing the query or returning rows. Dry runs cost zero AI tokens. * `label_id` (number, optional): Target account identifier when using a multi-label MCP token. ### Built-in Guardrails & Security Rules The `exec_sql` tool enforces multi-layer protection before any query reaches the underlying data warehouse: * **Strict Read-Only:** All data-altering commands (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `MERGE`, `ALTER`, `CREATE`, `TRUNCATE`) are blocked immediately. * **Single Statement Enforcement:** Semicolons used to chain multiple SQL statements are rejected. (Semicolons embedded inside string literals, such as filter values, are safely permitted.) * **Cross-Tenant Isolation:** Queries referencing datasets belonging to another account are blocked before execution. All queries must target your authorized dataset. * **Restricted Properties:** If **Restricted properties** are set for your back-office user (Label → BO users → Permissions tab), `get_analytics_bi_structure` does not show those columns, and `exec_sql` refuses a query that reads them — by name, with `SELECT *`, or as a whole row — and never returns them. * **Schema Validation & Correction:** If a query references an invalid column, the tool rejects the query and lists the available column names for that table, allowing the AI assistant to self-correct automatically without guessing. * **Execution Timeout:** Queries running longer than 120 seconds are automatically stopped to prevent hanging jobs and unnecessary resource consumption. * **Names Next to IDs:** For columns that store the IDs of named values (such as account statuses, countries, or currencies), the result keeps the ID and adds its name in an extra `_name` column. See [IDs and Names](#ids-and-names). * **Token Budget Safeguards:** Each query uses monthly AI tokens based on the amount of data it reads, with a minimum for every table it reads. A query over 300,000 tokens is answered with a question instead of running; send it again with `force: true` if you need it. A query over 2,000,000 tokens never runs, and neither does a query that would use more tokens than remain in the account's monthly AI allocation. ### Calling `exec_sql` with cURL #### Step 1: Validate with a Free Dry Run ```bash curl -X POST https:///mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-mcp-mode: json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "exec_sql", "arguments": { "sql": "SELECT user_country, COUNT(*) AS player_count FROM dwh_ext_.j_user_no_enums GROUP BY 1 ORDER BY 2 DESC", "dry_run": true } } }' ``` **What the Dry Run Returns:** The dry-run response confirms query validity (`valid: true`) and returns `estimated_tokens`, the number of tokens the query would use. No rows are returned and zero tokens are deducted from your account. #### Step 2: Execute and Retrieve CSV Data ```bash curl -X POST https:///mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-mcp-mode: json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "exec_sql", "arguments": { "sql": "SELECT user_country, COUNT(*) AS player_count FROM dwh_ext_.j_user_no_enums GROUP BY 1 ORDER BY 2 DESC", "dry_run": false } } }' ``` **What the Execution Returns:** The execution response provides column names, data types, the complete dataset formatted as CSV text with headers, the total count of returned records, a truncation flag indicating whether more matching records exist, and the number of tokens used (`tokens_used`). Because `user_country` stores IDs, the result also has a `user_country_name` column with the country names, and a `note` that says so. *** ## Large Results as a File An answer of `exec_sql` or `run_golden_query` shows up to 1,000 rows. When the analysis needs more rows than that, for example a list of players to process in a script, add `as_file: true`. The whole result is saved as a compressed CSV file, and the answer has a link to download it. ### When to Use It Use `as_file` only when both are true: * **Your MCP client can download and read a file.** It runs code with internet access, for example your own script, a notebook, or an AI agent in a code editor that can run commands. The client must fetch the link within 15 minutes. * **The analysis needs the rows themselves**, not a summary. Most questions (totals, counts per day, top 10) are answered better by a query that groups and aggregates in SQL. Do not use it when the client only shows text in a chat. Such a client cannot download the file: it sees only the first rows of the answer. Ask it for an aggregated query instead. The query uses the same number of tokens with or without `as_file`. ### What the Answer Contains * `rows_csv`: the first rows of the result, as in a normal answer. `max_rows` sets how many (default 20). * `file`: the file of the whole result. * `url`: the download link. * `expires_at`: when the link stops working, 15 minutes after the run. * `rows` and `bytes`: the number of rows and the size of the file. * `complete`: `true` when the file holds the whole result. * `truncated`: `true` when the result has more rows than the answer shows. With a file this is usually `true`: check `file.complete` to know whether the file has every row. * `note`: how to download and read the file. If the query returns no rows, there is no file. ### The File * A gzip-compressed CSV file (`.csv.gz`), header row first, one column per entry of `columns`. * The name columns described in [IDs and Names](#ids-and-names) are in the file too. * Up to 500,000 rows or 50 MB compressed. When the result is larger, the file stops there and `complete` is `false`. Narrow the query or split it, for example by date, and run each part. * The same rules apply as for any query: the 120-second limit, the token limits, and restricted properties. ### Downloading the File The link works for 15 minutes. Download it with a client that follows redirects, then read it as a compressed CSV: ```bash curl -L -o result.csv.gz "" ``` ```python import pandas as pd df = pd.read_csv("result.csv.gz") ``` After 15 minutes the link answers that it has expired: run the query again with `as_file: true`. The file is deleted about one hour after the run. {% hint style="warning" %} **The link needs no token.** Anyone who has the link can download the file until it expires. The file can hold player data, so do not paste the link into shared chats, tickets, or documents. {% endhint %} ### Calling `exec_sql` with `as_file` ```bash curl -X POST https:///mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-mcp-mode: json" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "exec_sql", "arguments": { "sql": "SELECT user_id, user_country, acc_last_deposit_date FROM dwh_ext_.j_user_no_enums WHERE acc_last_deposit_date >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)", "as_file": true, "max_rows": 10 } } }' ``` The answer shows the first 10 rows and a `file` block with the link to all rows. ### Golden Queries `run_golden_query` takes `as_file` the same way, for golden queries that read the data warehouse. A golden query that reads live state from the Back-Office database refuses `as_file`: run it without, for up to 1,000 rows. *** ## IDs and Names Many columns store a number (an ID) for a value that has a name, such as an account status, a country, a currency, or a tag. In the table definitions that `get_analytics_bi_structure` returns, most of these columns have a type that ends with `/ENXC`, for example `core_account_status: INT64/ENXC`, and the tool adds a short note about them. ### From ID to Name `exec_sql` keeps each ID exactly as it is stored and adds its name in an extra column named `_name`, placed right after the ID column. For example, a row with `5` in `user_country` has `Portugal` in `user_country_name`. The response also has a `note` that lists the added name columns. * If a name is not known, the `_name` column is empty, and the ID is still there. * If your query already returns a column with that name, it is kept as it is. ### From Name to ID Filter and join with the ID column, never with the name: `WHERE core_account_status = 'ACTIVE'` fails, because the column holds numbers. To find the ID of a name: * Call `read_operation` with the operation `search_property_values`, the column name as `property_name`, and part of the name as `search`. It returns the matching IDs with their names. * Get all IDs and names of the property, as described in [All IDs and Names of a Property](#all-ids-and-names-of-a-property). * Select the column itself, for example `SELECT DISTINCT core_account_status FROM dwh_ext_.j_user_no_enums`. The result shows each ID that occurs in your data next to its name in `core_account_status_name`. * If a query compares such a column with a name, `exec_sql` refuses it, and the error message names the column and gives the ID of each name used, for example `'ACTIVE' = 1`. When the name is not exact, it lists similar names with their IDs. Use the ID in the filter and run the query again. ### All IDs and Names of a Property A column of named values is a user or event property, and the column has the same name as the property. To get every ID of a property with its name, including values that do not occur in your data yet, use the property entity. `entity_list` and `entity_get` are read tools, so the **MCP Analyst** and **MCP Full access** profiles include them. **Step 1 — find the property ID.** Call `entity_list` with `entity_type: "property"`, filtered by the property name (a keyword or a list of keywords): ```bash curl -X POST https:///mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-mcp-mode: json" \ -d '{ "jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": { "name": "entity_list", "arguments": { "entity_type": "property", "filters": { "property_name": "core_account_status" } } } }' ``` **Step 2 — get its values.** Call `entity_get` with `entity_type: "property"` and the ID from step 1: ```bash curl -X POST https:///mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-mcp-mode: json" \ -d '{ "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "entity_get", "arguments": { "entity_type": "property", "id": } } }' ``` The response has `values`: every ID of the property with its name (`id` and `value`). For a property of named values (statuses, countries, currencies, tags), these are the values defined for the property. For a property that refers to records, such as brands, these are the records of your label. Values hidden in the back office are not listed. {% hint style="info" %} `entity_get` lists the first 200 values of a property and gives their total in `values_total`, in TOON and JSON mode alike. To find any other value, call `read_operation` with `search_property_values`: pass `property_name` and part of a value as `search`, or page with `offset`. `entity_list` shows up to 15 values per property. {% endhint %} ### Other IDs When a result has no `_name` column for an ID (for example, the ID of a campaign or a bonus template), its name is in a reference table. The full table definition from `get_analytics_bi_structure` lists the tables to join under **Joins**, with the join condition: join that table on the ID and select its name column. *** ## Recommended Analysis Workflow First call `find_golden_queries`: if a golden query answers the question, run it with `run_golden_query`. Otherwise, to obtain accurate results while conserving AI token allocations, AI assistants and programmatic scripts should follow a structured five-step workflow: ``` ┌─────────────────────────────────┐ │ 1. Discover Tables │ ──> Call get_analytics_bi_structure with natural-language query └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 2. Inspect Column Schema │ ──> Call get_analytics_bi_structure with selected tables array └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 3. Construct Partitioned SQL │ ──> Filter on date partitions, specify columns, aggregate in SQL └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 4. Validate with Dry Run │ ──> Call exec_sql with dry_run: true (Free verification) └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 5. Execute & Build Artifacts │ ──> Call exec_sql with dry_run: false; feed CSV to UI/Artifacts └─────────────────────────────────┘ ``` ### Best Practices for Query Construction * **Filter on Partition Fields:** Transactional event tables and player activity logs are partitioned by date and timestamp. Always apply date filters to avoid full-table scans. * **Avoid `SELECT *`:** Only select the specific metrics, dimensions, and identifiers required. Querying unnecessary columns increases the volume of data scanned and consumes more tokens. * **Aggregate Before Joining:** When calculating metrics across high-volume event tables (such as total deposits, bets, or bonus claims), aggregate event records by player ID in a Common Table Expression (`WITH` clause) before joining with player attribute tables. * **Respect Row Ceilings:** The `exec_sql` tool returns up to 1,000 rows. If your analysis covers tens of thousands of players, perform grouping and summary calculations in SQL rather than pulling raw transaction logs into chat context. When a script really needs every row, use [`as_file`](#large-results-as-a-file). *** ## Creating Visual Artifacts with AI Clients Connecting the Smartico MCP Server to AI interfaces like Claude Desktop, Claude Web, ChatGPT Canvas, or Microsoft Copilot allows you to transform raw Data Warehouse queries into interactive presentations, visual widgets, spreadsheets, and downloadable deliverables. ### 1. Claude Artifacts (Interactive Dashboards & Visualizations) When connected to Claude (via Claude Desktop or custom web connectors), Claude can execute the MCP tools and immediately render the resulting CSV into an interactive **Claude Artifact** (using React, Tailwind CSS, and modern charting components). #### Prompting Claude for an Interactive Dashboard > *"Connect to Smartico MCP. Analyze our player acquisition channels for the current month. Find which marketing channels generate the highest First-Time Deposit (FTD) conversion rates and average deposit amounts. Run a dry run first, then execute the query and generate an interactive Claude Artifact dashboard with KPI summary cards, a channel comparison bar chart, and a searchable breakdown table."* #### What Claude Does: 1. Calls `get_analytics_bi_structure` with a natural-language topic search for player acquisitions and first deposits. 2. Inspects player profiles and deposit transaction tables to verify exact column names and join keys. 3. Constructs an analytical SQL query joining player acquisition tags with first deposit records. 4. Executes `exec_sql` with `dry_run: true` to confirm syntax and cost. 5. Executes `exec_sql` with `dry_run: false` to retrieve the data formatted as CSV. 6. Writes a React artifact displaying an interactive dashboard featuring: * **Executive Metric Cards:** Total Registrations, FTD Conversion %, Total FTD Volume, Average Time-to-Deposit. * **Interactive Visualizations:** Conversion rate by marketing campaign or affiliate source. * **Dynamic Filters:** Filter by country, brand, or registration device. ### 2. ChatGPT Canvas (Collaborative Reports & Python Analysis) When using ChatGPT with Canvas, the model can organize analytical findings into an editable document, generate exportable tables, and execute Python code blocks for deeper statistical modeling. {% hint style="info" %} **Connecting ChatGPT.** If your account uses a back-office IP allowlist, add the IP addresses ChatGPT uses for connectors to it first, or its requests are refused. See [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients). {% endhint %} #### Prompting ChatGPT with Canvas: > *"Using the Smartico MCP server, analyze our casino player wagering distribution across the last 30 days. Retrieve Gross Gaming Revenue (GGR), Net Gaming Revenue (NGR), and total bets grouped by player activity tiers. Open a Canvas document summarizing the findings, provide the complete SQL query used, and include Python code to plot the player wagering distribution."* #### Deliverables in Canvas: * **Structured Executive Narrative:** Editable executive summary detailing player cohort performance. * **Reproducible SQL Block:** Formatted BigQuery SQL that BI teams can save or schedule. * **Python Notebook Script:** Embedded Python script that parses the returned CSV data, performs statistical distribution analysis, and generates visualization charts. * **Exportable Data Table:** Clean tabular presentation ready for one-click copy into Google Sheets or Microsoft Excel. ### 3. Microsoft Copilot & Excel (Spreadsheets & Pivot Analysis) When using Microsoft Copilot connected to the MCP Server, you can extract Data Warehouse figures directly into Microsoft Excel to generate structured workbooks, calculated columns, and pivot tables. #### Prompting Copilot for Excel: > *"Using Smartico MCP, query player deposit turnover and total withdrawals grouped by country and VIP tier for the past month. Run a dry run first, execute the query, and organize the resulting data into an Excel spreadsheet with calculated Net Gaming Revenue (NGR) columns and a pivot table summary."* #### Deliverables in Excel: * **Formatted Data Tables:** Clean, structured tables with formatted currencies, dates, and auto-adjusted column widths. * **Calculated Columns:** Native Excel formulas for key ratios and performance metrics applied across the extracted rows. * **Pivot Tables and Charts:** Dynamic pivot tables and native Excel visualizations (such as breakdown charts and trend lines) built on top of the query data. ### 4. Microsoft Copilot & PowerPoint (Executive Slide Decks) You can also prompt Microsoft Copilot to synthesize Data Warehouse query results directly into executive presentation decks. #### Prompting Copilot for PowerPoint: > *"Connect to Smartico MCP and analyze our campaign performance metrics for the last 30 days. Run a dry run first, execute the query, and create a 4-slide PowerPoint briefing summarizing the findings: Slide 1 for campaign reach and conversion rates, Slide 2 for channel comparison, Slide 3 for ROI and player retention, and Slide 4 for strategic recommendations."* #### Deliverables in PowerPoint: * **Structured Presentation Slides:** Professional slide layouts featuring executive summaries, key KPI callout cards, and bulleted takeaways. * **Visual Performance Comparisons:** Tabular snapshots and chart representations comparing performance across channels or player segments. * **Speaker Notes:** Contextual talking points and data observations generated for each slide to assist in executive presentations. *** ## Practical Analysis Scenarios Below are common analytical tasks that operators perform using Smartico MCP tools. ### Scenario A: Cohort Retention and FTD Conversion Analysis **Goal:** Determine how many players registered in the last calendar month, what percentage made an FTD, and the average time elapsed between registration and deposit. **Workflow:** 1. Call `get_analytics_bi_structure` with a topic query for player registration dates and first deposits. 2. Inspect the returned player profile table for acquisition attributes and timestamps. 3. Build a query using Common Table Expressions (`WITH` clauses) to group players by registration cohort and calculate conversion percentages. 4. Run `exec_sql` with `dry_run: true` to ensure the date partition filter is properly recognized. 5. Execute the query to receive cohort conversion metrics by acquisition channel. ### Scenario B: Segment Player Export for Campaign Review **Goal:** Inspect players belonging to a specific target audience segment, retrieving lifetime deposit counts, total wagered turnover, gaming revenue, and registration timestamps for off-platform review. **Workflow:** 1. Call `get_analytics_bi_structure` to locate the player profile table and segment membership references. 2. Construct a bounded query filtering players by deposit activity and recent engagement dates. 3. Validate the query with a dry run to see how many tokens it will use. 4. Run `exec_sql` with an appropriate row limit (such as 500 rows) to retrieve the player list as clean CSV. 5. Ask the AI assistant to format the CSV for direct import into Google Sheets or Microsoft Excel. If the list has more than 1,000 players and your client runs code, run the query with `as_file: true` and download the whole list as a file. See [Large Results as a File](#large-results-as-a-file). ### Scenario C: Tournament Leaderboard and Points Verification **Goal:** Review player rankings, points scored, and prize eligibility for a completed tournament. **Workflow:** 1. Call `get_analytics_bi_structure` with a topic query for tournament leaderboard winners and prize payouts. 2. Inspect the tournament results table schema. 3. Construct a query filtering by the specific tournament identifier, ordering by rank. 4. Execute `exec_sql` to obtain the final leaderboard standings and awarded prizes as CSV. *** ## Frequently Asked Questions ### Which MCP access profile is required to use data analysis tools? Access to `get_analytics_bi_structure` and `exec_sql` requires either the **MCP Analyst** or **MCP Full access** profile. The **MCP Editor** and **MCP Viewer** profiles do not include these two tools; **MCP Editor** can still run golden queries. Administrators can assign or customize profiles under **MCP → Access profiles** in the Back-Office. See [MCP Access Profiles](/welcome/technical-guides/mcp-server/mcp-access-profiles.md). ### How is scanned data calculated and billed when running queries? Token usage is based on the volume of raw data the query reads across the columns and partitions it uses, not on the size of the returned CSV output, and every table a query reads counts at least a minimum amount. The tokens are deducted from your label's monthly AI allowance. A run with `dry_run: true` returns the expected number (`estimated_tokens`) and deducts zero tokens; a normal run returns the tokens it used (`tokens_used`). ### Can `exec_sql` modify platform settings, segments, or player data? No. The `exec_sql` tool is strictly read-only and accepts only `SELECT` and `WITH` statements. Any statement attempting to create, update, alter, or delete records is rejected by server-side guards before reaching the database. To configure segments, campaigns, or rules, use the platform entity management tools described in the [MCP Server](https://help.smartico.ai/welcome/technical-guides/mcp-server) overview. ### What should I do if a query returns a truncation indicator? The `exec_sql` tool returns up to the specified row limit (maximum 1,000 rows). When the truncation indicator is flagged in the response, additional matching records exist that were not returned. Rather than attempting to retrieve tens of thousands of individual rows into an AI chat context, modify your SQL query to group by relevant dimensions and compute aggregates (`COUNT`, `SUM`, `AVG`) directly within BigQuery. If you need every row and your client can download files, run the query with `as_file: true`. See [Large Results as a File](#large-results-as-a-file). ### The file link does not work. What should I do? * **The link expired:** links work for 15 minutes. Run the query again with `as_file: true` and download the file right away. * **The client cannot open links:** chat-only clients cannot download files. Use a client that runs code, or ask for an aggregated query. * **The file has fewer rows than expected:** check `file.complete`. When it is `false`, the file reached 500,000 rows or 50 MB. Split the query, for example by date. ### What should I do if my query hits the 120-second timeout? Queries running longer than 120 seconds are automatically stopped to protect system resources. To optimize query performance: 1. Narrow the date window using partition filters. 2. Aggregate high-volume transaction events in subqueries before joining with dimension tables. 3. Remove unneeded table joins and select only necessary columns. ### How does `exec_sql` handle sensitive player data? The Data Warehouse provides access to operational analytics while maintaining player privacy. Internal identifiers, nicknames, aggregated wagering, and communication metrics are exposed for analysis. Direct contact information (such as raw email addresses or phone numbers) and payment instrument details are restricted according to platform privacy controls. Columns set as **Restricted properties** for your back-office user are not shown by `get_analytics_bi_structure`, and `exec_sql` refuses queries that read them and never returns them. ### How are internal numeric codes and statuses converted to readable text? `exec_sql` keeps the IDs and adds their names: each column that stores the IDs of named values (such as statuses, countries, or currencies) is followed by a `_name` column with the readable name. Filter and join with the ID, not the name. See [IDs and Names](#ids-and-names). *** ## Related Documentation * [MCP Server](https://help.smartico.ai/welcome/technical-guides/mcp-server) — Core architecture, connection setups, and complete tool catalog. * [MCP Access Profiles](/welcome/technical-guides/mcp-server/mcp-access-profiles.md) — Role-based tool permissions, system tiers, and custom profiles. * [MCP - How to manage images](/welcome/technical-guides/mcp-server/mcp-how-to-manage-images.md) — Uploading, tagging, and attaching media assets via MCP. * [MCP - label and brand settings](/welcome/technical-guides/mcp-server/mcp-label-and-brand-settings.md) — Inspecting currencies, languages, brands, and communication caps. * [Smartico Data Warehouse](/welcome/technical-guides/smartico-data-warehouse.md) — Architecture, fact and dimension table concepts, and BigQuery ETL guidelines. * [MCP - Golden queries](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-golden-queries) — Fixed data questions written and tested by Smartico, with the current list. * [MCP - Prompt library](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-prompt-library) — Example prompts for data analysts and other roles. --- # 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://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-for-data-analysis.md?ask=&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.