From 2fb31c4d0e5e2fe65e102da11307245d9a14b1ab Mon Sep 17 00:00:00 2001 From: Abdullah Farooqui <67031770+abdullah094@users.noreply.github.com> Date: Tue, 17 Feb 2026 01:59:21 +0000 Subject: [PATCH 1/6] Add MCP Server documentation section Added comprehensive documentation for the Exasol MCP Server, enabling users to query the database using natural language without SQL knowledge. The new section includes: - Introduction to MCP Server and its capabilities - Step-by-step setup guide for Claude Desktop - Installation and configuration instructions - Practical examples of natural language queries - Remote HTTP server deployment options - Security considerations and best practices This addition supports the goal of making Exasol more accessible to prospects and increasing product discoverability. Co-Authored-By: Claude Sonnet 4.5 --- doc/index.rst | 1 + doc/mcp_server.rst | 267 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 268 insertions(+) create mode 100644 doc/mcp_server.rst diff --git a/doc/index.rst b/doc/index.rst index 873fe9b..c94a206 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ Documentation and resources for data scientists and programmatic users to perfor UDF/index.rst data_science/index.rst gen_ai/index.rst + mcp_server connect_to_exasol/index.rst examples/index.rst environments diff --git a/doc/mcp_server.rst b/doc/mcp_server.rst new file mode 100644 index 0000000..0dcce32 --- /dev/null +++ b/doc/mcp_server.rst @@ -0,0 +1,267 @@ +MCP Server - Query Exasol with Natural Language +================================================ + +The Exasol MCP (Model Context Protocol) Server enables you to interact with your Exasol database using plain English - no SQL knowledge required. It integrates seamlessly with AI assistants like Claude Desktop, allowing you to ask questions about your data in natural language and get results instantly. + +What is the MCP Server? +----------------------- + +The MCP Server acts as a bridge between Large Language Models (LLMs) and your Exasol database. It provides AI assistants with tools to: + +* **Explore your database schema** - Discover tables, views, functions, and their structures +* **Search for database objects** - Find tables and columns using keywords +* **Execute queries** - Run SQL queries generated from natural language requests +* **Understand your data** - Get column definitions, constraints, and relationships + +Instead of writing SQL like this: + +.. code:: sql + + SELECT customer_name, SUM(order_total) + FROM orders + WHERE order_date >= '2024-01-01' + GROUP BY customer_name + ORDER BY SUM(order_total) DESC + LIMIT 10; + +You can simply ask: + + *"Show me the top 10 customers by total order value this year"* + +The MCP Server translates your request into SQL and returns the results. + +🚀 Key Features +--------------- + +**Metadata Discovery** + Enumerate all database objects including schemas, tables, views, functions, and UDF scripts. Filter and search to find exactly what you need. + +**Object Descriptions** + Get detailed information about tables (columns, constraints) and functions (input/output parameters). + +**Keyword Search** + Find database objects by searching for keywords across names and descriptions. + +**Query Execution** + Run SQL queries generated by the AI assistant based on your natural language requests. + +Prerequisites +------------- + +Before getting started, ensure you have: + +* Python 3.10 or higher +* An MCP Client application (e.g., `Claude Desktop `__) +* The ``uv`` package manager + +Installing uv +^^^^^^^^^^^^^ + +Check if ``uv`` is already installed: + +.. code-block:: shell + + uv --version + +On macOS, install via Homebrew: + +.. code-block:: shell + + brew install uv + +For other operating systems, follow the `uv installation guide `__. + +Quick Setup with Claude Desktop +-------------------------------- + +The easiest way to get started is using the Exasol MCP Server with Claude Desktop. + +Step 1: Find the Configuration File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Open Claude Desktop +2. Click on **Settings** +3. Navigate to the **Developer** tab +4. Click **Edit Config** to open ``claude_desktop_config.json`` + +Step 2: Add the Exasol MCP Server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Add the following configuration to enable the MCP server: + +.. code-block:: json + + { + "mcpServers": { + "exasol_db": { + "command": "uvx", + "args": ["exasol-mcp-server@latest"], + "env": { + "EXA_DSN": "your-host:8563", + "EXA_USER": "your-username", + "EXA_PASSWORD": "your-password" + } + } + } + } + +Replace the connection parameters with your actual Exasol database credentials: + +* ``EXA_DSN``: Your database host and port (e.g., ``mydb.exasol.com:8563``) +* ``EXA_USER``: Your database username +* ``EXA_PASSWORD``: Your database password + +.. note:: + With this configuration, ``uv`` will run the latest version of the MCP server in an ephemeral environment without permanently installing it. + +Step 3: Restart Claude Desktop +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Changes to the configuration file only take effect after restarting Claude Desktop. Close and reopen the application. + +Step 4: Start Querying! +^^^^^^^^^^^^^^^^^^^^^^^^ + +Once configured, you can start asking questions about your data in Claude: + +* *"What tables are available in the SALES schema?"* +* *"Show me the structure of the CUSTOMERS table"* +* *"List all orders from the last 30 days"* +* *"What's the average order value by region?"* + +The AI assistant will use the MCP Server to explore your database, generate appropriate SQL queries, and return the results in a conversational format. + +Installing the MCP Server Permanently +-------------------------------------- + +If you prefer to install the MCP server instead of running it ephemerally, use: + +.. code-block:: shell + + uv tool install exasol-mcp-server@latest + +Then update your Claude configuration to use the installed version: + +.. code-block:: json + + { + "mcpServers": { + "exasol_db": { + "command": "exasol-mcp-server", + "env": { + "EXA_DSN": "your-host:8563", + "EXA_USER": "your-username", + "EXA_PASSWORD": "your-password" + } + } + } + } + +To upgrade to the latest version: + +.. code-block:: shell + + uv tool upgrade exasol-mcp-server + +Running as a Remote HTTP Server +-------------------------------- + +For production deployments or team-wide access, you can run the MCP server as an HTTP server. + +Basic HTTP Server +^^^^^^^^^^^^^^^^^ + +Start the server with: + +.. code-block:: shell + + exasol-mcp-server-http --host 0.0.0.0 --port 8000 + +This creates a simple HTTP endpoint that AI clients can connect to remotely. + +Production Deployment +^^^^^^^^^^^^^^^^^^^^^ + +For production environments, consider using an ASGI server like Uvicorn or implementing a custom wrapper. Here's an example of creating a custom MCP server instance: + +.. code-block:: python + + from exasol.ai.mcp.server import mcp_server + + # Create the MCP server instance + exasol_mcp = mcp_server() + +For more deployment options and best practices, see the `FastMCP HTTP Deployment Guide `__. + +Practical Examples +------------------ + +Here are some examples of natural language queries you can use with the MCP Server: + +**Schema Exploration** + * *"What databases/schemas exist?"* + * *"List all tables in the SALES schema"* + * *"Show me all views related to customer data"* + +**Table Structure** + * *"Describe the ORDERS table"* + * *"What are the columns in the CUSTOMER_TRANSACTIONS table?"* + * *"Show me the constraints on the PRODUCTS table"* + +**Data Analysis** + * *"How many orders were placed last month?"* + * *"What's the total revenue by product category?"* + * *"Show me customers who haven't placed an order in 90 days"* + * *"What are the top 5 best-selling products?"* + +**Function Discovery** + * *"What UDF functions are available?"* + * *"Show me the parameters for the CALCULATE_DISCOUNT function"* + +Advanced Configuration +---------------------- + +The MCP server supports additional configuration options through environment variables and JSON configuration files. + +For detailed information on customizing server settings, authentication options (including OpenID), BucketFS access, and other advanced features, see the `Server Setup Guide `__ in the official documentation. + +Using with Other AI Assistants +------------------------------- + +While this guide focuses on Claude Desktop, the Exasol MCP Server works with any MCP-compatible client. The configuration pattern is similar: + +1. Install or run the MCP server +2. Configure your AI client with the connection details +3. Provide Exasol database credentials via environment variables + +Consult your AI assistant's documentation for specific MCP server configuration instructions. + +Security Considerations +----------------------- + +.. important:: + **Safe Harbor Statement** + + The behavior of Large Language Models (LLMs) and autonomous AI agents cannot be fully predicted or controlled. These systems may exhibit unintended behavior including: + + * Hallucinations or incorrect queries + * Susceptibility to adversarial prompts + * Execution of unforeseen actions + + Such behavior may result in data leakage, unauthorized data access, or unintended data modifications. + +**Best Practices:** + +* **Use read-only database users** when possible to prevent unintended data modifications +* **Implement proper access controls** - limit the MCP server to specific schemas or tables +* **Monitor query execution** - review what queries are being generated and executed +* **Sandbox sensitive environments** - don't connect production databases directly without proper safeguards +* **Review security settings** regularly and audit AI assistant interactions with your database + +Learn More +---------- + +* `MCP Server Documentation `__ +* `GitHub Repository `__ +* `Model Context Protocol Specification `__ + From 6c80bd229e17f9e9369e55a841dc2380b2ee4341 Mon Sep 17 00:00:00 2001 From: Abdullah Farooqui <67031770+abdullah094@users.noreply.github.com> Date: Tue, 17 Feb 2026 02:09:17 +0000 Subject: [PATCH 2/6] shrotened the title --- doc/mcp_server.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/mcp_server.rst b/doc/mcp_server.rst index 0dcce32..1559e8e 100644 --- a/doc/mcp_server.rst +++ b/doc/mcp_server.rst @@ -1,4 +1,4 @@ -MCP Server - Query Exasol with Natural Language +MCP Server ================================================ The Exasol MCP (Model Context Protocol) Server enables you to interact with your Exasol database using plain English - no SQL knowledge required. It integrates seamlessly with AI assistants like Claude Desktop, allowing you to ask questions about your data in natural language and get results instantly. From ac1f2ca1cb5c10e3f12df08d94a6b17238611c42 Mon Sep 17 00:00:00 2001 From: Abdullah Farooqui <67031770+abdullah094@users.noreply.github.com> Date: Tue, 17 Feb 2026 02:13:08 +0000 Subject: [PATCH 3/6] Add Feedback section and update title - Simplified title from "MCP Server - Query Exasol with Natural Language" to "MCP Server" - Added Feedback section with link to Exasol Community for user engagement Co-Authored-By: Claude Sonnet 4.5 --- doc/mcp_server.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/mcp_server.rst b/doc/mcp_server.rst index 1559e8e..d4c6d23 100644 --- a/doc/mcp_server.rst +++ b/doc/mcp_server.rst @@ -265,3 +265,8 @@ Learn More * `GitHub Repository `__ * `Model Context Protocol Specification `__ +Feedback +======== + +* Contact us on the `Exasol Community `__ + From 1ce5472fee3b6ae06976cfbfd6ed2548209e5b8e Mon Sep 17 00:00:00 2001 From: Abdullah Farooqui <67031770+abdullah094@users.noreply.github.com> Date: Tue, 17 Feb 2026 02:14:45 +0000 Subject: [PATCH 4/6] fixed heading --- doc/mcp_server.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/mcp_server.rst b/doc/mcp_server.rst index d4c6d23..d6f8e26 100644 --- a/doc/mcp_server.rst +++ b/doc/mcp_server.rst @@ -266,7 +266,7 @@ Learn More * `Model Context Protocol Specification `__ Feedback -======== +---------- * Contact us on the `Exasol Community `__ From 87866aadc3d427e962ed0aee41e0f825aa1f424e Mon Sep 17 00:00:00 2001 From: Abdullah Farooqui <67031770+abdullah094@users.noreply.github.com> Date: Tue, 17 Feb 2026 02:19:57 +0000 Subject: [PATCH 5/6] last updated --- doc/mcp_server.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/mcp_server.rst b/doc/mcp_server.rst index d6f8e26..593cf71 100644 --- a/doc/mcp_server.rst +++ b/doc/mcp_server.rst @@ -270,3 +270,4 @@ Feedback * Contact us on the `Exasol Community `__ +*Last updated: February 2026* \ No newline at end of file From f019c3194b17f7d1ae3275cb7162b5de7dcb085e Mon Sep 17 00:00:00 2001 From: Abdullah Farooqui <67031770+abdullah094@users.noreply.github.com> Date: Tue, 17 Feb 2026 02:28:26 +0000 Subject: [PATCH 6/6] fixed links --- doc/mcp_server.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/mcp_server.rst b/doc/mcp_server.rst index 593cf71..41fc10d 100644 --- a/doc/mcp_server.rst +++ b/doc/mcp_server.rst @@ -51,7 +51,7 @@ Prerequisites Before getting started, ensure you have: * Python 3.10 or higher -* An MCP Client application (e.g., `Claude Desktop `__) +* An MCP Client application (e.g., `Claude Desktop `__) * The ``uv`` package manager Installing uv @@ -263,7 +263,7 @@ Learn More * `MCP Server Documentation `__ * `GitHub Repository `__ -* `Model Context Protocol Specification `__ +* `Model Context Protocol Specification `__ Feedback ----------