fde-week3-agent
Enables natural-language querying of a SQLite database (Chinook sample) through tools for listing tables, describing schemas, executing read-only SQL queries, and summarizing results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fde-week3-agent which country has the most customers?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fde-week3-agent
A natural-language SQL agent that queries the Chinook sample database, built two ways: with raw function calling, then refactored to use the Model Context Protocol (MCP).
Built as week 3 of a 16-week forward-deployed engineering study plan. The goal: internalize the agent loop, understand why tool descriptions matter more than tool code, and see what MCP actually adds (and doesn't add) over raw function calling.
What it does
Answers natural-language questions like "which country has the most customers?" or "what are the top 5 best-selling artists by total revenue?" against a real SQLite database. The agent doesn't hardcode any SQL — it discovers the schema, writes queries, and interprets results dynamically.
Two working implementations of the same agent:
Raw function calling (
main.py): tools are Python functions intools.py, schemas are hardcoded intool_schemas.py, dispatched via a lookup dict inagent.py.MCP (
main_mcp.py): the same tools are exposed by an MCP server (mcp_server.py) and consumed by a client agent (mcp_client_agent.py). Tool schemas are fetched dynamically at startup, not hardcoded.
Related MCP server: mcp-chinookdb-server
Why both
The agent's behavior is identical across both implementations — same queries, same answers, same latency profile. That equivalence is the point. It demonstrates that MCP is a delivery mechanism for tools, not a change to how agents reason. Which one to pick is an organizational decision:
Raw is right when the agent and tools ship together and you don't need cross-agent reuse
MCP is right when tools are maintained separately, when the customer might swap agents later, or when the same tools need to serve multiple agents
The four tools
list_tables— discoverability. Returns table names.describe_table(name)— discoverability. Returns column schema for a given table.query_sql(sql)— read-only SELECT execution. Rejects INSERT, UPDATE, DELETE, DROP, and multi-statement input at the tool level (not just in the description).summarize_results(rows, question)— pure-LLM tool that generates natural-language summaries of query results.
Security model
The read-only constraint on query_sql is enforced in the tool's Python code, before the SQL reaches the database. The description tells the model the rule; the code enforces it. This is defense in depth: even if the model is confused, prompt-injected, or from a weaker model that ignores instructions, the destructive operation never reaches the database.
Same enforcement lives in the tool code whether accessed via raw dispatch or MCP. Refactoring to MCP doesn't move the security boundary — the boundary is in tools.py, which is unchanged across implementations.
Setup
git clone https://github.com/jordanmatusik24/fde-week3-agent
cd fde-week3-agent
uv syncCreate .env:
ANTHROPIC_API_KEY=sk-ant-...Download Chinook:
Invoke-WebRequest -Uri "https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite" -OutFile "chinook.db"Usage
Raw function calling agent:
uv run python main.py "How many customers are in the database?"
uv run python main.py "What are the top 5 best-selling artists by total revenue?"
uv run python main.py "Are there any customers who haven't made a purchase?"MCP agent (same questions, tools served over MCP protocol):
uv run python main_mcp.py "How many customers are in the database?"Test the MCP server standalone with the MCP inspector:
uv run mcp dev mcp_server.pyArchitecture
Raw:
main.py → agent.py (dispatch loop) → tools.py (implementations)
↑
tool_schemas.py (hardcoded)MCP:
main_mcp.py → mcp_client_agent.py → MCP protocol over stdio → mcp_server.py → tools.py
↑
schemas generated from decoratorsFindings
Description quality dominates tool code quality. A tool with a perfect implementation and a vague description gets misused. A tool with a middling implementation and a sharp description gets called correctly. The description is the model's API contract.
Discoverability tools prevent schema hallucination. Without
list_tablesanddescribe_table, an agent asked to query an unknown database invents plausible-looking but wrong SQL based on training-data conventions. With them, the agent observes the schema before writing SQL, and correctness follows.Parallel tool calls happen when the description hints at them. The
describe_tabledescription ends with "you can call it in parallel for multiple tables in one turn." The model then bundles 3-4 describes into a single turn on multi-table queries, cutting latency 2-3× vs sequential discovery.Constraints enforced only in prompt/description are voluntary. Constraints in tool code are mandatory. The SELECT-only check has to live in
tools.py, not just in the description, because the description is documentation and code is the wall. This distinction is the answer to every customer security review question about what an agent can and cannot do.MCP doesn't change agent behavior. Same queries, same answers, same latency profile across the two implementations. MCP shifts where tools are maintained, not how agents reason.
Stack
Python 3.12, managed by uv
Anthropic SDK for Claude Sonnet 4.5
MCP Python SDK for the MCP server and client
typer for the CLI
Chinook sample database — a fictional digital music store schema
Available Tools
4 toolsdescribe_tableARead-onlyIdempotent
Return the column schema for a table.
Call this before writing any SQL that references a table you haven't described yet. You can call it in parallel for multiple tables in one turn. Returns an error if the table name doesn't exist — use list_tables to see valid names.
Args: name: The exact table name, case-sensitive, as returned by list_tables.
Inputs: name (required).
list_tablesARead-onlyIdempotent
List all tables in the connected Chinook database.
Call this FIRST when you don't yet know what data is available. Returns a JSON object with a 'tables' key holding a list of table names. Each name can then be passed to describe_table to learn the columns. Cheap to call; use it freely rather than guessing table names.
Inputs: no named parameters.
query_sqlARead-onlyIdempotent
Execute a single SELECT statement against the database and return results.
This tool is READ-ONLY: INSERT, UPDATE, DELETE, DROP, and any other non-SELECT statement will be rejected. Multiple statements chained with semicolons will also be rejected — send one SELECT at a time.
Returns an object with: columns (list of column names), row_count, rows (list of row objects), and truncated (true if there were more than 100 rows, in which case only the first 100 are returned).
If you don't know the schema, call list_tables and describe_table FIRST. Never invent column or table names — verify them by describing the tables involved.
Args: sql: A single, valid SQLite SELECT statement. Use standard SQL. You may include JOIN, WHERE, GROUP BY, ORDER BY, LIMIT, and aggregate functions. Do not include a trailing semicolon.
Inputs: sql (required).
summarize_resultsARead-only
Produce a natural-language summary of query results.
Use this ONLY when the rows need narrative interpretation (multiple rows, aggregate patterns, comparisons across groups). For single-row lookups or trivially small results, answer directly in your response text without calling this tool.
Args: rows: The 'rows' list returned from query_sql. question: The user's original question, verbatim.
Inputs: rows (required), question (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct, non-overlapping purpose: listing tables, describing schema, executing SQL queries, and summarizing results. No two tools could be confused for the same task.
All tools follow a consistent verb_noun pattern in snake_case (list_tables, describe_table, query_sql, summarize_results), making the set predictable and easy to use.
4 tools perfectly cover the essential workflow for a read-only database agent: discover tables, inspect schema, run queries, and summarize results. Each tool earns its place with no unnecessary additions.
The set covers the core workflow well, but lacks a tool for quickly previewing sample data or obtaining table statistics, which would require writing a query manually. Minor gap, but functional.
Maintenance
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
MCP server exposing the Backtest360 engine API as tools for AI agents.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to interact with SQLite databases by querying schemas, executing SQL, and inspecting table metadata. It supports safe database access through configurable read-only modes, query timeouts, and dry-run execution plans.MIT
- AlicenseAqualityDmaintenanceMCP server providing LLMs with safe, read-only access to the Chinook SQLite sample database, including schema exploration and SQL query execution.11MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that enables LLMs to safely explore and query any SQLite database via natural language. It exposes tools for listing tables, describing schemas, and executing SELECT/WITH queries with built-in safety guards like write prevention and row limits.MIT
- AlicenseNot gradedqualityDmaintenanceMCP tool server providing SQLite database access for AI agents.MIT