Chat With Your Database Agent Template

• What it does: Runs one Database Analyst agent that turns plain-English questions into read-only queries against your Supabase database using MCP tools list_tables and execute_sql, then returns short summaries plus tables or numbers.
• Best for: teams that want self-serve answers from live data without SQL, dashboards for every question, or manual CSV exports
• Apps used: Supabase (via Custom MCP URL), personal access token for Authorization
• Setup time: 15 to 30 minutes (includes read-only DB role, token, and MCP tool wiring)

Chat With Your Database ships a focused agent plus a Supabase MCP tool so users ask in natural language and get grounded results. This template acts as a starting point: any app, instructions, and agents can be updated as required for your own use case—simply ask Max (Agent Builder) to update the workflow as needed. Last verified from workflow config on April 2026. Includes common failure modes and fixes.

---

Problem this solves

• Business users need counts, recent rows, and schema context from Postgres without learning SQL or waiting on analysts.
• Exporting spreadsheets for every ad hoc question is slow and goes stale quickly.
• You want read-only access patterns so chat cannot mutate production data by accident.

---

What this agent does

This template can:

• Accept user messages from a text trigger (widget, chat, or API).
• Call list_tables when the user asks what exists or when the agent is unsure which table to use (not on every turn).
• Call execute_sql with SELECT queries only, always with a LIMIT (default 20 rows, maximum 100) and ORDER BY when sorting matters.
• Prefer relevant columns instead of SELECT * unless the user explicitly wants all columns; use ILIKE for case-insensitive text filters.
• Return 0 rows honestly, suggest rephrasing, and avoid inventing data when the database cannot answer.
• Present multiple rows as a markdown table and counts or totals as a short sentence, with a one- to two-sentence summary before the table.

---

How it works

1. User sends a natural-language question through the workflow trigger.
2. Database Analyst decides whether it needs schema discovery; if so, it calls list_tables and summarizes what is available.
3. The agent builds a SELECT query (with limits and ordering as needed) and calls execute_sql.
4. Supabase MCP runs the query against your project (read-only path when configured correctly) and returns rows or aggregates.
5. The agent summarizes the outcome in plain language, then shows a table or a single number as appropriate.
6. If results hit the row cap, the reply states that results are limited (for example “Showing the top 20 results”).

---

Requirements

• A Supabase project and permission to create a read-only database role (see setup SQL) or an equivalent governance model your org accepts.
• A Supabase personal access token (PAT) under Account → Access Tokens for the MCP Authorization: Bearer header.
• The MCP Server URL must include your project ref and read_only=true plus features=database, for example: https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true&features=database.
• In the tool node, enable the Supabase MCP connection, set streamable HTTP, and allow only list_tables and execute_sql (matches the template export intent).

---

Setup guide

1. Clone the template and open it in AgentSpace. On the canvas, use the Quickstart Setup sticky (including Connect Supabase to Your Workflow for the MCP URL and headers) and the Starter Prompts sticky for test ideas.
2. Supabase read-only role: In the Supabase SQL Editor, run the read-only role script from the canvas sticky (create readonly_mcp_user, grant USAGE on schema public, SELECT on tables, and default privileges for future tables). Use a strong password stored securely.
3. Access token: Generate a PAT in Supabase Account → Access Tokens and copy it for the MCP header.
4. MCP tool node: Open Supabase_DB, set enabled, set the MCP URL with your real project_ref (you can copy project_ref from your Supabase project URL; replace [project_ref] or YOUR_PROJECT_REF in the template), choose streamable connection type, and set Authorization to Bearer YOUR_PAT_TOKEN.
5. Filter tools: Enable only list_tables and execute_sql on the MCP tool (matches safe surface area).
6. Agent: Confirm the Database Analyst node is connected to the MCP tool on the tools edge; adjust instructions only if your schema or policies need extra guardrails.
7. Open Playground and test. The canvas Starter Prompts sticky suggests examples such as:
   • What tables do you have access to? (expects list_tables then a short summary).
   • How many users signed up this week?
   • Show me the 10 most recent orders (expects ORDER BY and LIMIT).
   • What's the total revenue this month? or List the top 5 customers by order count (expects aggregates or ranked SELECTs with limits).
   • Edge cases: Delete all test users should be refused (read-only, no writes). Show me ALL records should still cap at 100 rows and state that results are limited.
8. Publish to your channel when results look correct.

Common issues and fixes

• Tool disabled or 401 errors: Enable the MCP tool node and verify the PAT is pasted in the Authorization header and is not expired. Confirm the project ref in the URL matches your Supabase project.
• Empty results: Check filters and date ranges; verify data exists in the table. Ask the user to rephrase or widen filters as the agent instructions suggest.
• Too many or too few rows: The agent caps at 100 rows even when the user says “all”; tighten WHERE clauses or raise limits in instructions only within your policy (default limit 20 in agent copy).
• Write or destructive requests: The agent must refuse INSERT, UPDATE, DELETE, and DDL. If a user asks to delete or change data, they should get a refusal, not a query.
• Wrong table chosen: Rely on list_tables for discovery questions; add table naming hints in the agent instructions if your schema uses non-obvious names.

Customization knobs

• Tighten default LIMIT or allowed date ranges in the Database Analyst instructions for large tables.
• Add org-specific rules (PII columns to avoid, required filters) in the same instructions block.
• Ask Max (Agent Builder) to add approval steps, a second agent, or exports if your governance model requires it.

Security checklist before going live

• read_only=true appears in the MCP URL.
• A dedicated read-only DB user (or approved equivalent) exists; production credentials are not reused casually.
• PAT is dedicated to this workflow only (rotate if leaked); only list_tables and execute_sql are enabled on the tool.

---

Apps used

---

Use cases

• Weekly metrics: “How many signups this week or this month?” Best for growth and ops.
• Revenue and rankings: “Total revenue this month” or “top N customers by order count” when your schema supports it. Best for finance-aligned ops and product.
• Operational lookups: “Last 10 recent orders” or similar time-sorted lists. Best for CS and on-call leads.
• Schema exploration: “What tables do you have access to?” before deeper questions. Best for new team members onboarding to the project.

---

Example prompts and outputs

Example 1: Aggregate

Prompt (user): “How many orders were placed this month?”

Output: Short sentence with the count from a SELECT aggregate scoped to the current month (per your created_at column naming).

Example 2: Recent rows

Prompt (user): “Show me recent users.”

Output: One- to two-sentence summary, then a markdown table of user fields (for example id, email, created_at) with ORDER BY created_at DESC and LIMIT 20.

Example 3: Discovery

Prompt (user): “What tables do you have access to?”

Output: list_tables run once, then a concise overview of what each table is likely for (agent summarizes; user does not need raw SQL).

Example 4: Read-only refusal (edge case)

Prompt (user): “Delete all test users.”

Output: No destructive SQL; the agent should refuse because only SELECT is allowed (align with agent instructions and MCP read_only=true).

---

Why you need this template

• Natural-language access to live Postgres data with explicit read-only tooling patterns.
• Predictable guardrails: SELECT only, row caps, and honest handling of empty or unanswerable questions.
• Starting point: extend with more agents, exports, or governance by editing the canvas or asking Max (Agent Builder).

---