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..41fc10d --- /dev/null +++ b/doc/mcp_server.rst @@ -0,0 +1,273 @@ +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. + +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 `__ + +Feedback +---------- + +* Contact us on the `Exasol Community `__ + +*Last updated: February 2026* \ No newline at end of file