Skip to main content

Connect AI Agents to Dremio with MCP

Model Context Protocol (MCP) is an open-source standard developed by Anthropic that lets AI agents securely interact with external data systems. MCP provides a consistent mechanism for tool discovery and data retrieval, reducing integration complexity and enabling enterprise-grade governance over AI-to-data connections.

With MCP, your AI assistant becomes an intelligent extension of Dremio. Instead of switching between chat interfaces and SQL clients, you can explore data, investigate issues, and build data products through natural conversation. The AI agent reasons across your data catalog, writes and executes queries, and iterates based on results — turning multi-step data workflows into simple conversations.

Whether you're an analyst exploring unfamiliar datasets, an engineer debugging query performance, or a data architect building semantic layers, MCP enables an agentic data experience through the AI tools you already use.

Dremio's existing access controls are enforced — agents operate with the same permissions as the authenticated user.

Connection Options​

Choose the connection method based on your AI client:

Connection TypeAI ClientsAuthenticationBest For
Dremio-Hosted MCP ServerClaude.ai, ChatGPTOAuth 2.0Web-based AI clients with OAuth support
Self-Hosted MCP ServerClaude Code, Claude Desktop, Cursor, VS CodePersonal Access Token (PAT)Local/CLI-based AI clients
Recommendation

Use the Dremio-hosted MCP Server when possible. It provides OAuth support with guaranteed user identity propagation and requires no local installation.

Option 1: Dremio-Hosted MCP Server​

Use this option to connect Claude.ai or ChatGPT to Dremio using OAuth authentication.

Prerequisites​

Before you begin, ensure you have:

  • A Dremio Cloud account with admin access to create OAuth applications
  • An AI chat client subscription:
    • Claude: Enterprise, Pro, Max, or Team plan (Claude pricing)
    • ChatGPT: Plus or Enterprise plan

Review the official documentation for your AI client:

Step 1: Create a Native OAuth Application​

  1. Log in to Dremio Cloud.
  2. Navigate to Organization Settings > OAuth Applications.
  3. Click Create OAuth Application.
  4. Select Native Application as the application type.
  5. Enter a Name for your application (e.g., "Claude MCP Connector").
  6. Add the Redirect URLs for your AI client (see below).
  7. Click Create.
  8. Copy the Client ID — you'll need this in Step 3.

Redirect URLs by AI Client​

Add all of the following redirect URLs for Claude:

Claude redirect URLs
https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback,http://localhost/callback,http://localhost

Step 2: Get Your MCP Endpoint​

Your MCP endpoint depends on your Dremio control plane region:

Control PlaneMCP Endpoint
UShttps://mcp.dremio.cloud/mcp/{project_id}
EUhttps://mcp.eu.dremio.cloud/mcp/{project_id}

To find your endpoint:

  1. Go to Project Settings > Project Overview.
  2. Copy the MCP endpoint value.
note

Replace {project_id} with your actual Dremio project ID.

Step 3: Configure Your AI Client​

  1. In Claude, navigate to Admin Settings > Connectors.
  2. Click Add custom connector.
  3. Enter the following:
    • Server name: Dremio (or a descriptive name of your choice)
    • Remote MCP server URL: Your MCP endpoint from Step 2
  4. Expand Advanced settings and enter:
    • OAuth client ID: The client ID from Step 1
    • OAuth client secret: Leave blank
  5. Click Add.
  6. Open the Tools menu and enable the Dremio connector.

Option 2: Self-Hosted MCP Server​

Use this option to connect Claude Code, Claude Desktop, Cursor, or other local MCP clients using a personal access token (PAT).

Prerequisites​

Before you begin, ensure you have:

  • uv Package Manager installed
  • Python 3.11 or later
  • Git
  • A PAT from Dremio
  • Your Dremio project ID (found in Project Settings > Project Overview)
  • Node.js (required for Claude Desktop)

Step 1: Install the Dremio MCP Server​

Clone the repository and install dependencies:

Command for cloning the repository and installing dependencies 
# Clone the repository
git clone https://github.com/dremio/dremio-mcp.git
cd dremio-mcp

# Install dependencies
uv sync

Verify the installation:

Command for verifying the installation 
uv run dremio-mcp-server --help

You should see output showing available commands: run, tools, and config.

Step 2: Configure the Dremio Connection​

Create the Dremio configuration file:

Command for creating the Dremio configuration 
uv run dremio-mcp-server config create dremioai \
    --uri <dremio_uri> \
    --pat <your_pat> \
    --project-id <project_id>

Parameters:

ParameterDescriptionExample
--uriDremio API endpointSee table below
--patPersonal access tokendapi123... or @/path/to/token.txt
--project-idYour Dremio project IDa843a0bb-2694-4426-9b94-9243bca9199e

Dremio URI by Environment:

EnvironmentURI
Dremio Cloud (US)https://api.dremio.cloud or prod
Dremio Cloud (EU)https://api.eu.dremio.cloud or prodemea
Self-managedhttps://<coordinator-host>:<port> (default port: 9047)
Security Tip

To avoid exposing your PAT in shell history, store it in a file and reference it with the @ prefix:

Command for storing the PAT in a file for security
echo "your_pat_here" > ~/.dremio/token
chmod 600 ~/.dremio/token
uv run dremio-mcp-server config create dremioai \
    --uri prod \
    --pat @~/.dremio/token \
    --project-id your_project_id

Verify the configuration:

Command for verifying the Dremio configuration 
uv run dremio-mcp-server config list --type dremioai

Step 3: Configure Your AI Client​

Claude Code is a command-line tool for agentic coding. Run the following command to add the Dremio MCP server:

Command for adding the Dremio MCP server to Claude Code
# Navigate to your working directory
cd /path/to/your/project

# Add the Dremio MCP server
claude mcp add dremio \
    --command "uv" \
    --args "run,--directory,/path/to/dremio-mcp,dremio-mcp-server,run"

Replace /path/to/dremio-mcp with the actual path where you cloned the repository.

Verify the connection:

Command for verifying the Claude Code connection
# Start Claude Code
claude

# Check MCP servers
/mcp

You should see dremio listed with available tools like GetUsefulSystemTableNames, GetSchemaOfTable, and RunSqlQuery.

Verify Your Connection​

After configuration, test your connection with a simple query:

  1. Open your AI chat client.
  2. Start a new conversation.
  3. Ask: "List the datasets available in Dremio".
  4. If using OAuth (hosted server), complete the sign-in flow when prompted.

The AI should respond using Dremio MCP tools. You'll see tool calls like:

  • GetUsefulSystemTableNames — Lists system tables
  • GetSchemaOfTable — Gets table schema information
  • RunSqlQuery — Executes SQL queries
Example MCP interaction 
You: What tables are available in my Dremio instance?

Claude: I'll check what tables are available in your Dremio instance.

[Calling GetUsefulSystemTableNames]

Based on the Dremio system tables, here are the key tables available:
- sys.reflections — Information about data reflections
- sys.jobs — Query job history
- sys.materializations — Materialized view information
...

Server Modes​

The Dremio MCP Server supports three modes that control what capabilities are exposed:

ModeDescriptionUse Case
FOR_DATA_PATTERNSAllows exploring tables and querying dataData discovery, analytics, pattern analysis
FOR_SELFEnables Dremio system introspectionWorkload analysis, performance monitoring
FOR_PROMETHEUSConnects to Prometheus for metricsEnhanced insights with Dremio metrics

Configure modes in your config.yaml:

Server mode configuration 
tools:
  server_mode: FOR_DATA_PATTERNS  # Single mode
  # server_mode: FOR_DATA_PATTERNS,FOR_SELF  # Multiple modes

Advanced Configuration​

Configuration File Reference​

The full configuration file (~/.config/dremioai/config.yaml) supports these options:

Full configuration file reference 
dremio:
  uri: https://api.dremio.cloud          # Dremio API endpoint
  pat: "@~/.dremio/token"                 # PAT (inline or file reference with @)
  project_id: your-project-id            # Required for Dremio Cloud
  enable_search: false                   # Enable semantic search (optional)
  allow_dml: false                       # Allow creating views (optional)

tools:
  server_mode: FOR_DATA_PATTERNS         # Server mode(s)

# Optional: Prometheus integration for self-managed deployments
# prometheus:
#   uri: https://prometheus.example.com
#   token: your-prometheus-token

Logging​

Log files are stored in platform-specific directories:

PlatformLog Location
Linux~/.local/share/dremioai/logs/dremioai.log
macOS~/Library/Logs/dremioai/dremioai.log
Windows%LOCALAPPDATA%\dremioai\logs\dremioai.log

Enable JSON logging:

Command for enabling JSON logging 
uv run dremio-mcp-server run --enable-json-logging

Disable file logging:

Command for disabling file logging 
uv run dremio-mcp-server run --no-log-to-file

Troubleshooting​

Common Issues​

IssueCauseSolution
"Authentication failed"Incorrect OAuth client ID or redirect URLsVerify the client ID matches exactly and all redirect URLs are configured in the OAuth application
"Invalid redirect URI"Missing redirect URL in OAuth appAdd all required redirect URLs to your OAuth application in Dremio
"Connection timeout"Incorrect MCP endpoint URLEnsure the URL includes https:// and the correct region
"Unauthorized" or "403 Forbidden"User lacks project accessVerify your Dremio user has access to the specified project
"PAT invalid" or "401 Unauthorized"Expired or revoked tokenGenerate a new PAT in Dremio
"Project not found"Incorrect project IDCopy the correct project ID from Project Settings > Project Overview
"MCP server not found"Claude Desktop config path wrongVerify the --directory path points to the cloned repository
"uv: command not found"uv not installed or not in PATHInstall uv: curl -LsSf https://astral.sh/uv/install.sh | sh
"Python version error"Python < 3.11Run uv python install 3.11 or install Python 3.11+

Claude Code Specific Issues​

IssueCauseSolution
"Dynamic client registration failed"Hosted MCP server doesn't support DCRUse the self-hosted MCP server option with PAT authentication
MCP server not appearing in /mcpConfiguration not loadedRestart Claude Code or check the mcp.json configuration

Diagnostic Commands​

Command for checking the Dremio configuration 
uv run dremio-mcp-server config list --type dremioai
Command for checking the Claude Desktop configuration 
uv run dremio-mcp-server config list --type claude
Command for testing tools directly 
uv run dremio-mcp-server tools list
Command for viewing logs on macOS
tail -f ~/Library/Logs/dremioai/dremioai.log

Support​

The Dremio MCP Server is an open-source project and is not covered by Dremio Support Policies. For issues and feature requests, see: