MariaDB · looreenz · May 28, 2026
diff --git a/mariadb-mcp/SKILL.md b/mariadb-mcp/SKILL.md
@@ -4,143 +4,21 @@ description: "How to connect AI agents to MariaDB using the Model Context Protoc
 ---
 
 # MariaDB MCP Server
+## 💡 Quick Context
+- **Baseline Version:** See [MariaDB Versioning Context](../_shared/versioning.md).
+- **Requirements:** Python 3.11+, `uv` package manager, MariaDB server.
 
 *Last updated: 2026-05-25*
 
 The Model Context Protocol (MCP) lets AI agents connect to external tools and data sources. The MariaDB MCP Server gives agents direct, controlled access to a MariaDB database — reading schemas, running queries, and optionally performing vector/semantic search — without requiring the developer to write integration code.
 
-The server is open source (MIT), maintained by the MariaDB Foundation at [github.com/MariaDB/mcp](https://github.com/MariaDB/mcp).
+## Documentation
 
-> **Requires:** Python 3.11+, `uv` package manager, MariaDB server.
-
-## What Agents Can Do
-
-With the MariaDB MCP Server connected, an agent can:
-
-- List databases and tables
-- Read table schemas including foreign key relationships
-- Run read-only SQL queries (`SELECT`, `SHOW`, `DESCRIBE`)
-- Create databases
-- Perform semantic/vector search on stored documents (when embedding provider is configured)
-
-Write operations (`INSERT`, `UPDATE`, `DELETE`) are disabled by default.
-
-## Installation
-
-```bash
-git clone https://github.com/MariaDB/mcp
-cd mcp
-cp .env.example .env
-# Edit .env with your database credentials
-```
-
-**Minimum `.env` configuration:**
-```
-DB_HOST=127.0.0.1
-DB_PORT=3306
-DB_USER=myuser
-DB_PASSWORD=mypassword
-DB_NAME=mydatabase
-MCP_READ_ONLY=true
-```
-
-**Run the server:**
-```bash
-uv run server.py
-```
-
-## Connecting Claude Code, Cursor, or Windsurf
-
-Use the official server from a local clone (see Installation). Point your MCP config at `uv run server.py` and the `.env` file with database credentials.
-
-**Claude Code** (project-scoped `.mcp.json` at the repo root):
-
-```json
-{
-  "mcpServers": {
-    "mariadb": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "/absolute/path/to/mcp",
-        "run",
-        "server.py"
-      ],
-      "envFile": "/absolute/path/to/mcp/.env"
-    }
-  }
-}
-```
-
-Or add via CLI (replace paths):
-
-```bash
-claude mcp add mariadb -- uv --directory /absolute/path/to/mcp run server.py
-```
-
-**Cursor / VS Code** — same `mcpServers` block in MCP settings; use absolute paths.
-
-**SSE or HTTP** — run `uv run server.py --transport sse` (or `http`) and connect to the URL; see [MariaDB/mcp README — Integration](https://github.com/MariaDB/mcp#integration---claude-desktopcursorwindsurfvscode).
-
-> **Not official:** PyPI package `mcp-server-mariadb` (`uvx mcp-server-mariadb`) is a third-party project, not maintained by the MariaDB Foundation. Prefer `github.com/MariaDB/mcp` unless you have a specific reason to use the PyPI package.
-
-## Available Tools
-
-| Tool | What it does |
-|---|---|
-| `list_databases` | Lists all databases the user can access |
-| `list_tables` | Lists tables in a database |
-| `get_table_schema` | Returns column definitions and types |
-| `get_table_schema_with_relations` | Includes foreign key relationships |
-| `execute_sql` | Runs a read-only SQL query |
-| `create_database` | Creates a new database |
-
-## Vector & Semantic Search (Optional)
-
-When an embedding provider is configured, additional tools are available for building RAG pipelines directly through the MCP interface:
-
-| Tool | What it does |
-|---|---|
-| `create_vector_store` | Creates a vector store table |
-| `insert_docs_vector_store` | Embeds and stores documents |
-| `search_vector_store` | Semantic similarity search |
-| `list_vector_stores` | Lists available vector stores |
-| `delete_vector_store` | Removes a vector store |
-
-**Configure an embedding provider in `.env`:**
-```
-EMBEDDING_PROVIDER=openai   # or gemini or huggingface
-OPENAI_API_KEY=sk-...
-```
-
-For building pure vector search applications, using MariaDB's native `VECTOR` type and `VEC_DISTANCE_*` functions directly is more efficient. The MCP vector tools are useful for quick prototyping and when AI agents need to manage the vector store themselves. See the `mariadb-vector` skill for native vector SQL.
-
-## Security: Read-Only Access
-
-The `MCP_READ_ONLY=true` setting enforces read-only at the application level by filtering queries. For production or shared environments, also restrict at the database level:
-
-```sql
-CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'password';
-GRANT SELECT, SHOW DATABASES ON *.* TO 'mcp_agent'@'localhost';
--- Do NOT grant INSERT, UPDATE, DELETE, DROP
-```
-
-Application-level read-only alone is not sufficient — database-level privileges are the reliable guarantee.
-
-## Key Gotchas
-
-- **`uv` is required**: the MCP server uses `uv` for dependency management, not `pip` directly. Install: `pip install uv` or `brew install uv`.
-- **Read-only is not fully enforced in software**: rely on database-level privileges, not just `MCP_READ_ONLY=true`.
-- **Vector tools are disabled** until `EMBEDDING_PROVIDER` is set in `.env`.
-- **Connection pooling** defaults to 10 connections — tune `MCP_MAX_POOL_SIZE` for concurrent agent use.
-- **SSL/TLS**: configure `DB_SSL_CA`, `DB_SSL_CERT`, `DB_SSL_KEY` in `.env` for remote or production databases.
-- **Enterprise version**: MariaDB also offers a MariaDB Enterprise MCP Server with additional access control and multi-agent features. See [mariadb.com/products/mcp-server](https://mariadb.com/products/mcp-server/).
-
-## Sources
-
-- [MariaDB MCP Server — GitHub](https://github.com/MariaDB/mcp)
-- [MariaDB MCP Server product page — mariadb.com](https://mariadb.com/products/mcp-server/)
-- [Connect Claude Code to tools via MCP — Claude Code Docs](https://code.claude.com/docs/en/mcp)
-- [MCP Hackathon winner announcement — mariadb.org](https://mariadb.org/model-context-protocol-mcp-hackathon-integration-track-winner/)
-
-*For topics not covered here, see the official MariaDB documentation at [mariadb.com/docs](https://mariadb.com/docs).*
+- [Deep Dive Index]
+  - [Overview](docs/overview.md)
+  - [Installation](docs/installation.md)
+  - [Connecting](docs/connecting.md)
+  - [Vector & Semantic Search](docs/vector-search.md)
+  - [Security](docs/security.md)
+  - [Key Gotchas](docs/gotchas.md)
+- [Sources](docs/sources.md)
diff --git a/mariadb-mcp/docs/connecting.md b/mariadb-mcp/docs/connecting.md
@@ -0,0 +1,35 @@
+# Connecting Claude Code, Cursor, or Windsurf
+
+Use the official server from a local clone (see Installation). Point your MCP config at `uv run server.py` and the `.env` file with database credentials.
+
+## Claude Code (project-scoped `.mcp.json` at the repo root):
+
+```json
+{
+  "mcpServers": {
+    "mariadb": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/mcp",
+        "run",
+        "server.py"
+      ],
+      "envFile": "/absolute/path/to/mcp/.env"
+    }
+  }
+}
+```
+
+Or add via CLI (replace paths):
+```bash
+claude mcp add mariadb -- uv --directory /absolute/path/to/mcp run server.py
+```
+
+## Cursor / VS Code
+Same `mcpServers` block in MCP settings; use absolute paths.
+
+## SSE or HTTP
+Run `uv run server.py --transport sse` (or `http`) and connect to the URL; see [MariaDB/mcp README — Integration](https://github.com/MariaDB/mcp#integration---claude-desktopcursorwindsurfvscode).
+
+> **Not official:** PyPI package `mcp-server-mariadb` (`uvx mcp-server-mariadb`) is a third-party project, not maintained by the MariaDB Foundation. Prefer `github.com/MariaDB/mcp` unless you have a specific reason to use the PyPI package.
diff --git a/mariadb-mcp/docs/gotchas.md b/mariadb-mcp/docs/gotchas.md
@@ -0,0 +1,8 @@
+# Key Gotchas
+
+- **`uv` is required**: the MCP server uses `uv` for dependency management, not `pip` directly. Install: `pip install uv` or `brew install uv`.
+- **Read-only is not fully enforced in software**: rely on database-level privileges, not just `MCP_READ_ONLY=true`.
+- **Vector tools are disabled** until `EMBEDDING_PROVIDER` is set in `.env`.
+- **Connection pooling** defaults to 10 connections — tune `MCP_MAX_POOL_SIZE` for concurrent agent use.
+- **SSL/TLS**: configure `DB_SSL_CA`, `DB_SSL_CERT`, `DB_SSL_KEY` in `.env` for remote or production databases.
+- **Enterprise version**: MariaDB also offers a MariaDB Enterprise MCP Server with additional access control and multi-agent features. See [mariadb.com/products/mcp-server](https://mariadb.com/products/mcp-server/).
diff --git a/mariadb-mcp/docs/installation.md b/mariadb-mcp/docs/installation.md
@@ -0,0 +1,23 @@
+# Installation
+
+```bash
+git clone https://github.com/MariaDB/mcp
+cd mcp
+cp .env.example .env
+# Edit .env with your database credentials
+```
+
+**Minimum `.env` configuration:**
+```
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=myuser
+DB_PASSWORD=mypassword
+DB_NAME=mydatabase
+MCP_READ_ONLY=true
+```
+
+**Run the server:**
+```bash
+uv run server.py
+```
diff --git a/mariadb-mcp/docs/overview.md b/mariadb-mcp/docs/overview.md
@@ -0,0 +1,24 @@
+# MariaDB MCP Server: Overview
+
+## What Agents Can Do
+
+With the MariaDB MCP Server connected, an agent can:
+
+- List databases and tables
+- Read table schemas including foreign key relationships
+- Run read-only SQL queries (`SELECT`, `SHOW`, `DESCRIBE`)
+- Create databases
+- Perform semantic/vector search on stored documents (when embedding provider is configured)
+
+Write operations (`INSERT`, `UPDATE`, `DELETE`) are disabled by default.
+
+## Available Tools
+
+| Tool | What it does |
+|---|---|
+| `list_databases` | Lists all databases the user can access |
+| `list_tables` | Lists tables in a database |
+| `get_table_schema` | Returns column definitions and types |
+| `get_table_schema_with_relations` | Includes foreign key relationships |
+| `execute_sql` | Runs a read-only SQL query |
+| `create_database` | Creates a new database |
diff --git a/mariadb-mcp/docs/security.md b/mariadb-mcp/docs/security.md
@@ -0,0 +1,11 @@
+# Security: Read-Only Access
+
+The `MCP_READ_ONLY=true` setting enforces read-only at the application level by filtering queries. For production or shared environments, also restrict at the database level:
+
+```sql
+CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'password';
+GRANT SELECT, SHOW DATABASES ON *.* TO 'mcp_agent'@'localhost';
+-- Do NOT grant INSERT, UPDATE, DELETE, DROP
+```
+
+Application-level read-only alone is not sufficient — database-level privileges are the reliable guarantee.
diff --git a/mariadb-mcp/docs/sources.md b/mariadb-mcp/docs/sources.md
@@ -0,0 +1,8 @@
+# Sources
+
+- [MariaDB MCP Server — GitHub](https://github.com/MariaDB/mcp)
+- [MariaDB MCP Server product page — mariadb.com](https://mariadb.com/products/mcp-server/)
+- [Connect Claude Code to tools via MCP — Claude Code Docs](https://code.claude.com/docs/en/mcp)
+- [MCP Hackathon winner announcement — mariadb.org](https://mariadb.org/model-context-protocol-mcp-hackathon-integration-track-winner/)
+
+*For topics not covered here, see the official MariaDB documentation at [mariadb.com/docs](https://mariadb.com/docs).*
diff --git a/mariadb-mcp/docs/vector-search.md b/mariadb-mcp/docs/vector-search.md
@@ -0,0 +1,19 @@
+# Vector & Semantic Search (Optional)
+
+When an embedding provider is configured, additional tools are available for building RAG pipelines directly through the MCP interface:
+
+| Tool | What it does |
+|---|---|
+| `create_vector_store` | Creates a vector store table |
+| `insert_docs_vector_store` | Embeds and stores documents |
+| `search_vector_store` | Semantic similarity search |
+| `list_vector_stores` | Lists available vector stores |
+| `delete_vector_store` | Removes a vector store |
+
+**Configure an embedding provider in `.env`:**
+```
+EMBEDDING_PROVIDER=openai   # or gemini or huggingface
+OPENAI_API_KEY=sk-...
+```
+
+For building pure vector search applications, using MariaDB's native `VECTOR` type and `VEC_DISTANCE_*` functions directly is more efficient. The MCP vector tools are useful for quick prototyping and when AI agents need to manage the vector store themselves. See the `mariadb-vector` skill for native vector SQL.