DataAgentConnector

Blueprint for spinning up read-only SQL data agents from any SQLAlchemy-compatible database. Indexes schema and column content into LanceDB and exposes MCP + REST tools so LLMs and UIs can safely explore your data.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio magnuss0-dataagentconnector uvx run uvicorn app.main:app --reload \
  --env ENVIRONMENT="development" \
  --env LLM_API_KEY="your_api_key_here" \
  --env LLM_BASE_URL="https://api.your-llm-provider.com" \
  --env LLM_MODEL_NAME="default-model" \
  --env DATABASES_TOML_PATH="databases.toml"

How to use

DataAgentConnector provides a read-only SQL gateway and a set of MCP-backed tools to interact with databases via SQLAlchemy. It exposes an MCP interface at /mcp for operations like listing databases, showing tables and views, describing metadata, retrieving distinct values, previewing data, performing content-based searches, and executing read-only queries. In addition, a REST layer under /widgets/ is available for UI integration. To use the server, configure your databases in databases.toml and set up your LLM provider in .env, then run the server so the MCP endpoints can be queried by your MCP client or UI. The toolset includes: get_databases for discovering connected databases, show_tables/show_views for metadata retrieval, describe_table/describe_view for DDL-like details, get_distinct_values for sampling categorical data, preview_table for quick data glimpses, find_relevant_columns_and_content for BM25-based content search, query_database for safe read-only SQL execution, and join_path for suggested join strategies across tables.

How to install

Prerequisites:

Python 3.10+ installed
uvicorn available (via uvx) or installed as a dependency
Access to a database (or several) via connection strings defined in databases.toml

Clone the repository and navigate into it:

git clone https://github.com/MagnusS0/DataAgentConnector.git cd DataAgentConnector
Create and/or edit the environment configuration:
- databases.toml: add your database connections, e.g.
  
  [databases.my_database] connection_string = "sqlite:///path/to/your/database.db" description = "My local SQLite database"
  
  [databases.another_database] connection_string = "postgresql://user:password@localhost:5432/another_database" description = "Another PostgreSQL database"
- .env: set your LLM provider details
  
  LLM_API_KEY=your_api_key_here LLM_MODEL_NAME=default-model LLM_BASE_URL=https://api.your-llm-provider.com
Install Python dependencies (via Poetry or pip as you prefer). If using pipx/uv, you can install runtime deps via:

uv sync --group ai
Run the server:

uv run uvicorn app.main:app --reload
Access MCP endpoints at http://localhost:8000/mcp or the REST endpoints under http://localhost:8000/widgets/ once the server is running.

Additional notes

Notes and tips:

The server enforces read-only access for SQL queries to protect data integrity; ensure your allowed_sql_commands are configured in tool.dac.settings to reflect safe operations.
If you modify databases.toml, restart the server to pick up changes.
Environment variables for LLM providers should be kept secret and managed securely (use a secrets manager in production).
The REST endpoints under /widgets/ can be wired to a UI to present database metadata and query capabilities in a user-friendly way.
If you encounter connection issues, verify network access from the host to the target databases and confirm that the connection_string formats are supported by SQLAlchemy.
For indexing and annotation tasks, the system uses an MVCC-like workflow with embeddings via sentence-transformers; ensure enough resources are available for indexing steps.