{"slug": "db-semantic-mcp-gives-ai-agents-a-safe-semantic-map-of-your-database", "title": "db-semantic-mcp Gives AI Agents a Safe Semantic Map of Your Database", "summary": "A developer built db-semantic-mcp, an MCP server that provides AI coding agents with a safe semantic map of databases without executing SQL. The tool exposes table names, column types, comments, sample rows, and LLM-powered schema search, supporting PostgreSQL and SQL Server. It works with MCP-compatible clients like OpenCode, Claude Code, and Cursor, and uses a Markdown file to bridge physical schema and business vocabulary.", "body_md": "AI agents are getting database access before they understand databases.\n\nThat is the wrong order.\n\nA real production database is rarely self-explanatory. The important table is not always named `orders`\n\n. The customer table may be called `t_bd_customer`\n\n. A field may carry a business-critical status code that only makes sense if you know the system behind it. A warehouse may split raw operational data, cleaned dimensions, and aggregated facts across schemas with names like `ods`\n\n, `dw`\n\n, and `staging`\n\n. The schema is technically visible, but the meaning is not.\n\nSo I built [ db-semantic-mcp](https://github.com/chncaesar/db-semantic-mcp): a small MCP server that gives AI coding agents a safe semantic map of a database.\n\nIt exposes table names, column types, comments, sample rows, and LLM-powered schema search. It supports PostgreSQL and SQL Server. It works with MCP-compatible agent clients such as OpenCode, Claude Code, Cursor, and similar tools.\n\nIt deliberately does not execute SQL.\n\nThat boundary is the point.\n\nMost database integrations for agents start with query execution. Give the model a connection string, add a SQL tool, maybe add a read-only role, and let it ask the database questions.\n\nThat can be useful. It is also a big first step.\n\nBefore an agent writes or runs a query, it needs to answer more basic questions:\n\nThose are not SQL execution questions. They are database understanding questions.\n\n`db-semantic-mcp`\n\nfocuses on that layer. It gives the agent enough structure to navigate the database without turning the database into a remote-control surface.\n\nThe server provides four MCP tools:\n\n| Tool | Purpose |\n|---|---|\n`list_tables` |\nList database tables with schema names and table comments. |\n`describe_table` |\nInspect columns, types, nullability, and column comments. |\n`sample_data` |\nFetch a small number of example rows from a table. |\n`search_schema` |\nSearch tables and columns semantically using an OpenAI-compatible LLM. |\n\nThe first three tools are direct metadata and sampling operations. They let an agent inspect the database the way a developer would: list tables, open one table, look at columns, check a few rows.\n\nThe fourth tool is where the semantic layer matters.\n\n`search_schema`\n\ncombines a cached schema snapshot with an optional Markdown file that describes your business terms, naming conventions, and database design decisions. The model can then resolve natural-language requests such as:\n\n```\ncustomer receivables\nWIP inventory\nsales order\n应收账款\n```\n\ninto the tables and columns that are likely to matter.\n\nThis is especially useful for databases where the table names are technically consistent but not obvious to an agent. ERP databases, legacy SQL Server systems, and large warehouse schemas often fall into that category.\n\nThere is no new ontology format to learn. There is no vector database to deploy. There is no separate catalog service.\n\nYou write a Markdown file.\n\nFor example:\n\n```\n# Database Semantic Context\n\n## Naming Conventions\n\n- `ods.*` tables contain raw operational data.\n- `dw.*` tables contain modeled fact and dimension tables.\n- `staging.*` tables are temporary ETL staging tables.\n\n## Business Terms\n\n| Business term | Table(s) |\n| --- | --- |\n| Customer | ods.bd_customer, dw.dim_customer |\n| Inventory | dw.fact_inventory_snapshot |\n| WIP / work in progress | dw.fact_wip_by_lot |\n\n## Design Decisions\n\n- Monetary amounts are stored in integer cents.\n- `_modified_at` columns are incremental sync watermarks.\n- Soft deletes use `doc_status = 'D'`.\n```\n\nThat file is loaded into the schema search prompt. It is the bridge between the database's physical structure and the vocabulary developers or business users actually use.\n\nThe important design choice is that the semantic layer stays close to the team. It can live next to the project. It can be reviewed like documentation. It can be changed without re-indexing a vector store or migrating a metadata system.\n\nBecause the first safe primitive an agent needs is not always a query tool.\n\nIf an agent can execute arbitrary SQL, even read-only SQL, the safety problem becomes larger immediately. You need to think about permissions, row-level access, query cost, data exfiltration, audit logs, and prompt injection through data. Those problems are solvable, but they are not free.\n\n`db-semantic-mcp`\n\ntakes a narrower position: give the agent visibility into structure and meaning first.\n\nThat makes the tool useful in more conservative environments. A team may be comfortable exposing table metadata, comments, and a few sample rows to an agent long before it is comfortable giving the agent a general SQL execution surface. The server still connects to the database, so it should be configured carefully, but its product boundary is intentionally smaller.\n\nThe result is not a text-to-SQL platform. It is the layer before text-to-SQL. It helps the agent understand where it is.\n\nThe first implementation supported PostgreSQL. The current version also supports SQL Server through the same MCP interface.\n\nThe backend is selected from the `DATABASE_URL`\n\nscheme:\n\n```\npostgresql://user:pass@localhost:5432/mydb\nsqlserver://user:pass@host:1433?database=mydb&encrypt=disable\n```\n\nThat matters because a lot of valuable business data is not sitting in a neat Postgres app database. It is in SQL Server. It is in ERP systems. It is in databases with thousands of tables, inconsistent comments, historical naming conventions, and schemas that only a few people inside the company understand.\n\nFor those databases, `db-semantic-mcp`\n\nincludes cache controls such as schema filters and table-prefix filters. If a SQL Server database contains thousands of tables but the useful business tables share prefixes like `t_pur_`\n\n, `t_sal_`\n\n, `t_stk_`\n\n, or `t_bd_`\n\n, the schema cache can focus on those areas.\n\nThis is not about making a toy database easier to query. It is about making messy real databases navigable by an agent without pretending they are clean.\n\nOnce registered with an MCP client, the workflow is simple.\n\nAn agent can start broad:\n\n```\nlist_tables schema=dw\n```\n\nThen inspect a candidate table:\n\n```\ndescribe_table table=dw.fact_inventory_snapshot\n```\n\nThen look at a few rows:\n\n```\nsample_data table=dw.fact_inventory_snapshot limit=3\n```\n\nOr search semantically:\n\n```\nsearch_schema keyword=\"customer receivables\"\nsearch_schema keyword=\"应收账款\"\n```\n\nThe agent does not need to guess table names from memory. It does not need the user to paste schema dumps into every prompt. It can ask the database metadata server for the relevant context, then use that context in the coding task.\n\nFor example, if the task is to modify an ETL pipeline, add a reporting endpoint, or debug a data mapping issue, the agent can first discover the database shape instead of hallucinating it.\n\nThat is the value: better grounding before action.\n\nThe server is configured through environment variables:\n\n```\nDATABASE_URL=postgresql://user:pass@localhost:5432/mydb\nSEMANTIC_FILE=/path/to/SCHEMA.md\nLLM_BASE_URL=https://api.openai.com/v1\nLLM_API_KEY=sk-...\nLLM_MODEL=gpt-4o-mini\n```\n\n`LLM_API_KEY`\n\nis only required for semantic search. The metadata tools work without it.\n\nAn MCP client can register it as a local server:\n\n```\n{\n  \"mcp\": {\n    \"db-semantic\": {\n      \"type\": \"local\",\n      \"command\": \"pg-semantic-mcp\",\n      \"environment\": {\n        \"DATABASE_URL\": \"postgresql://user:pass@host:5432/dbname\",\n        \"SEMANTIC_FILE\": \"/path/to/SCHEMA.md\",\n        \"LLM_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\nThe command name still uses `pg-semantic-mcp`\n\nfor compatibility with the original PostgreSQL-only version. The package and repository now use the broader `db-semantic-mcp`\n\nname because the server supports multiple backends.\n\n`db-semantic-mcp`\n\nis useful when an agent needs database context but should not start by executing SQL.\n\nGood fits include:\n\nIt is not trying to replace a BI platform, a warehouse catalog, a governance product, or a complete text-to-SQL system.\n\nIt is a small missing primitive: let the agent understand the database before it acts on the database.\n\nI think agent tooling is going to split into two categories.\n\nSome tools will make agents more powerful. They will let agents execute, mutate, deploy, administer, and automate more of the system.\n\nOther tools will make agents better grounded. They will expose state, constraints, readiness, history, metadata, and semantics in ways that reduce guessing.\n\n`db-semantic-mcp`\n\nbelongs to the second category.\n\nIt does not make the agent omnipotent. It gives the agent a map. In real engineering work, that is often the safer and more useful first step.\n\nProject: `github.com/chncaesar/db-semantic-mcp`", "url": "https://wpnews.pro/news/db-semantic-mcp-gives-ai-agents-a-safe-semantic-map-of-your-database", "canonical_source": "https://dev.to/antonio_zhu_e726fd856cd86/db-semantic-mcp-gives-ai-agents-a-safe-semantic-map-of-your-database-2j8i", "published_at": "2026-08-11 00:38:27+00:00", "updated_at": "2026-08-11 01:15:23.988412+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models", "ai-agents"], "entities": ["db-semantic-mcp", "PostgreSQL", "SQL Server", "OpenCode", "Claude Code", "Cursor"], "alternates": {"html": "https://wpnews.pro/news/db-semantic-mcp-gives-ai-agents-a-safe-semantic-map-of-your-database", "markdown": "https://wpnews.pro/news/db-semantic-mcp-gives-ai-agents-a-safe-semantic-map-of-your-database.md", "text": "https://wpnews.pro/news/db-semantic-mcp-gives-ai-agents-a-safe-semantic-map-of-your-database.txt", "jsonld": "https://wpnews.pro/news/db-semantic-mcp-gives-ai-agents-a-safe-semantic-map-of-your-database.jsonld"}}