Index Agentica

Data analysis agent stack

An agent that answers questions from your data: it queries DuckDB files, a ClickHouse warehouse or Postgres through read-only MCP servers, runs heavier analysis in a sandbox, reads spreadsheets and PDFs, and is tested and traced so you can trust the numbers.

Type
Stack
Author
Agentica Author
Published
Last verified

Use case

Answer business and research questions from tabular data (local files, a cloud warehouse or an operational Postgres) with SQL and Python, show the queries behind every number, and never change the data unless a human allows it.

Components

RoleComponentWhy
Agent harnessClaude Agent SDKClaude Code's agent loop as a Python or TypeScript library, with MCP connections, subagents and permission controls over which tools run automatically and which need approval.
Local files and lake dataMotherDuck / DuckDB MCP ServerThe open-source local server opens DuckDB files read-only by default, as well as in-memory databases, S3-hosted DuckDB and MotherDuck. The managed remote server at api.motherduck.com/mcp adds OAuth and MotherDuck's Dives, Flights and Guides.
WarehouseClickHouse MCP ServerClickHouse's official server runs queries read-only by default. Writes need CLICKHOUSE_ALLOW_WRITE_ACCESS=true and DROP-style statements need a second flag, and it takes typed query parameters so values are kept apart from SQL.
Operational PostgresPostgres MCP ProRestricted mode limits the server to read-only transactions and caps execution time, and EXPLAIN and index-tuning tools help the agent understand why a query is slow before it runs it.
Many databases, fixed queriesMCP Toolbox for DatabasesWhen the agent should only run vetted queries, Toolbox lets you define parameterized SQL tools across many engines instead of handing over raw SQL.
Analysis sandboxE2BRuns the agent's pandas, plotting or modeling code in an isolated cloud sandbox instead of on your machine. Internet access is on by default and can be turned off or limited with allow and deny lists.
Spreadsheets and documentsMarkItDownConverts Excel, PDF, Word and other files to Markdown so the agent can read tables and reports that are not in a database. It reads with the privileges of its process, so give it only the files it needs.
Answer testingEvidentlyOpen-source evals with LLM judges and text checks. Turn a Report into a Test Suite with pass/fail conditions and run it in CI against a set of questions with known answers.
TracingLangfuseRecords every model call, tool call and SQL statement, so a reviewer can see which query produced which number, and so real questions can become test cases.

How the pieces fit

A data analysis agent works in a loop: understand the question, find the right tables, write a query, check the result, maybe compute more in Python, then explain the answer with the query behind it. The stack maps one component to each step and keeps the agent read-only unless a human allows more.

  1. Discover the schema first. All three database servers have tools for listing databases and tables or reading schema. ClickHouse's list_tables is paginated and can leave out column details to keep responses small. ClickHouse also suggests reading an AGENTS schema database first if you keep one. MotherDuck's remote server can serve Guides: Markdown documents with your metric definitions and join conventions, so the agent stops guessing what "active user" means.
  2. Query where the data lives. Use DuckDB/MotherDuck for local files, Parquet on S3 and MotherDuck, ClickHouse for the warehouse and Postgres MCP Pro for the application database. Search indexes and caches have their own servers too: Elastic Agent Builder for ES|QL and Redis.
  3. Move big results out of the context. MotherDuck's docs note that every tool result passes through the model's context. Ask for aggregates, not raw rows. When the agent needs a large extract for modeling, have it write the data to a file and process it in the E2B sandbox with pandas, then return only the summary and the chart.
  4. Read what isn't in a database. Convert spreadsheets and PDF reports with MarkItDown, or with Docling for complex layouts. The document conversion guide compares the options.
  5. Show the work. Require the final answer to include the SQL it ran. Langfuse keeps the full trace, so anyone can re-run the query.

The harness here is the Claude Agent SDK. Any MCP-capable harness works; see adding MCP servers to Claude Code for one client's setup.

Keep it read-only by default

Test the answers, not just the queries

A query can run without errors and still answer the wrong question. Keep a set of questions with known answers, such as last quarter's revenue or this month's sign-ups, and run the agent against them on every prompt or model change. Evidently turns these checks into a Test Suite with pass/fail conditions for CI. Its LLM-judge evals can also grade the written explanation, not just the final number. Evaluate an AI agent covers building that dataset from real traces.

Variations

Directory entries in this stack

Related

Sources

Machine-readable