MCP Server:
AI Database Interface

Every AI integration with a database is point-to-point. There is no standard layer.

Most AI workflows that need to read or write data from a database require custom code for each use case. You write a tool, hardcode the schema, handle the query, return the result. It works, but it does not scale. Every new request means a new function. And if the schema changes, you update the code.

The deeper problem is that the AI model has no way to explore the data itself. It only knows what you hardcode into the system prompt or the tool definition. Ask it a question that touches a table you did not think to describe and the answer falls apart.

What I wanted was a protocol layer. Define the tools once at the database level, not at the question level. Let Claude figure out what to call, in what order, to answer whatever the user asks.

If Claude can discover the schema itself, you never need to hardcode any of it.

MCP (Model Context Protocol) is the right abstraction here. It is an open protocol for giving AI models structured, permissioned access to tools and data. You define tools as TypeScript functions with a name, a description, and a Zod schema for the inputs. Claude reads the tool list, decides which ones to call, calls them, reads the result, and continues. The model orchestrates the tools, not the developer.

The design decision that made this genuinely useful was schema discovery. Instead of hardcoding the database structure anywhere, I wrote two PostgreSQL functions that expose live table names and column types through Supabase's RPC layer. Claude can call them at the start of any session and understand the full database structure from scratch without any prior knowledge of it.

That changes the dynamic. You do not tell Claude about your database and then ask it questions. You connect the server, Claude looks around, and then you have a conversation about your actual data.

Eight tools, live schema introspection, and one non-obvious deployment detail.

• 01
  Tool design

  Eight tools covering the full surface: query_table (read all rows), filter_table (read by column value), insert_row, update_row, delete_row, list_tables (schema discovery), get_table_columns (column introspection), and say_hello for connection testing. Each tool has a description Claude reads to decide when to use it, and a Zod schema that validates inputs before any database call is made.
• 02
  Schema introspection via Postgres RPC

  Two custom PostgreSQL functions query the information_schema directly: one returns all table names visible to the current user, the other returns column names and types for a given table. Both are exposed through Supabase's RPC layer and called from the MCP tools without any hardcoded schema knowledge. Claude calls them first, then reasons about the results.
• 03
  Supabase integration

  The Supabase JavaScript client handles all database communication. The MCP server instantiates a single client at startup using the project URL and service role key, and every tool shares that connection. No connection pooling overhead for a server this size, and the service role key bypasses row-level security so the server has full read-write access to all tables it needs.
• 04
  Subprocess context: the non-obvious part

  Claude Desktop spawns the MCP server as a child process from its own working directory, not the project folder. That means a standard relative path to the .env file resolves to the wrong location and the environment variables never load. The fix is fileURLToPath combined with import.meta.url to derive the correct absolute path relative to the source file, regardless of where the process is launched from. This is not documented anywhere obvious and cost a full day to trace.
• 05
  End-to-end testing inside Claude Desktop

  Tested by connecting Claude Desktop to the running server and running a live session against a real Supabase database. Claude discovered 23 tables, returned the full schema for a 35-column orders table, queried the products table, inserted a test row, and confirmed the insert including the generated UUID and timestamp. No SQL written by the user at any point.

Claude can now walk into a database it has never seen and reason about it from scratch.

The test session ran against a real Supabase database. I connected the server, opened Claude Desktop, and asked: "What tables are available and what does the orders table look like?" Claude called list_tables, got 23 results, then called get_table_columns for orders and returned a structured view of 35 columns with their types. I had not told it anything about the database.

Then I asked for the products. It called filter_table with no column filter, returned all rows formatted as a clean table with names, categories, prices, and stock levels. Then I asked it to add a test product and confirm the insert. It used two tools in sequence, insert_row and then query_table, and returned the new row including the UUID and timestamp that Postgres generated.

This is the pattern I now use when building AI agents that need to work with a client's live data. Define the tools at the database level rather than the question level, expose them through MCP, and Claude handles the orchestration. The schema discovery means the server works against any Postgres database without modification.

The source is on GitHub. The architecture works the same way whether the database has 5 tables or 50.