Dx

Use natural language to write and execute queries on your organizational data in DX Data Cloud!

About

The DX MCP Server is a Python-based tool that empowers AI applications, such as Claude for Desktop and Cursor, to interact with your DX Data Cloud database. The server includes tools to:

• establish a connection to your Postgres database, allowing the AI to actively formulate and execute queries on the database
• find/utilize context about your software entities and their relationships and scorecards via DX catalog tools

Learn more about the Model Context Protocol (MCP).

Note: DX intends for the CLI to become the primary interface for AI agents and is investing in it as the long-term direction beyond the MCP server. Both interfaces remain supported.

Demo

https://github.com/user-attachments/assets/c6ce12a5-4562-4b44-b235-2d04871c3142

Getting Started

There are two ways to use the DX MCP Server:

1. Remote hosting (recommended): Connect to our hosted server at https://ai.getdx.com/mcp
2. Local hosting: Run the server on your machine

Prerequisites

• A DX account with access to Data Cloud

• For remote hosting:

  • A DX API token, generated in your DX Account Settings
    • Admin users can create an organization API token with read scopes granted, and non-admin users can generate personal access tokens to authenticate with the MCP server.

• For local hosting:

  • Python 3.10 or higher
  • Your database connection URL (configured on DX's DB Users settings page)
  • A DX API token, generated in your DX Account Settings
    • Admin users can create an organization API token with read scopes granted, and non-admin users can generate personal access tokens to authenticate with the MCP server.

---

Option 1: Remote Hosting (Recommended)

The hosted MCP server uses streamable HTTP transport and is available at https://ai.getdx.com/mcp. This option requires no local installation; just configure your AI client with the mcp using http transport and provided with a valid DX API Token.

Claude Code

Run this command in your terminal:

claude mcp add --transport http dx-mcp https://ai.getdx.com/mcp --header "Authorization: Bearer [YOUR_DX_API_TOKEN]"

Cursor

Add this configuration to your MCP settings (Cursor > Settings > Cursor Settings > MCP):

{
  "mcpServers": {
    "dx-mcp": {
      "url": "https://ai.getdx.com/mcp",
      "headers": {
        "Authorization": "Bearer [YOUR_DX_API_TOKEN]"
      }
    }
  }
}

---

Option 2: Local Installation

If you prefer to run the DX MCP Server locally, you can install it via PyPI or run it from source.

Installation Method 1: Install from PyPI

Install the package using pip:

pip install dx-mcp-server

Note for macOS users: If you encounter an "externally-managed-environment" error, use pipx instead:

pipx install dx-mcp-server

Installation Method 2: Clone from Source

Clone this repository to run from source:

git clone https://github.com/get-dx/dx-mcp-server
cd dx-mcp-server

Configuration

Once installed, configure your AI client with the appropriate settings:

Claude Code

Run this command in your terminal (adjust based on your installation method):

# If installed via pip/pipx
claude mcp add dx-mcp-server --env DB_URL=YOUR_DB_URL --env WEB_API_TOKEN=YOUR_DX_API_TOKEN -- $(which dx-mcp-server)

Claude for Desktop

Click Claude > Settings > Developer > Edit Config and add:

If you installed via pip:

{
  "mcpServers": {
    "dx-mcp": {
      "command": "dx-mcp-server", 
      "args": ["run"],
      "env": {
        "DB_URL": "YOUR-DATABASE-URL",
        "WEB_API_TOKEN": "YOUR_DX_API_TOKEN"
      }
    }
  }
}

If you're running from source:

{
  "mcpServers": {
    "dx-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/dx-mcp-server", "run", "-m", "dx_mcp_server", "run"],
      "env": {
        "DB_URL": "YOUR-DATABASE-URL",
        "WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
      }
    }
  }
}

Cursor

Click Cursor > Settings > Cursor Settings > MCP > Add new global MCP Server and add:

If you installed via pip:

{
  "mcpServers": {
    "dx-mcp": {
      "command": "dx-mcp-server", 
      "args": ["run"],
      "env": {
        "DB_URL": "YOUR-DATABASE-URL",
        "WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
      }
    }
  }
}

If you're running from source:

{
  "mcpServers": {
    "dx-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/dx-mcp-server", "run", "-m", "dx_mcp_server", "run"],
      "env": {
        "DB_URL": "YOUR-DATABASE-URL",
        "WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
      }
    }
  }
}

Configuration Parameters

• DB_URL (required): Your DX Data Cloud Postgres connection string. Get this from DX DB Users settings.
  • Format: postgresql://username:password@host:port/database
• WEB_API_TOKEN: Your DX API Token (either an organization token or a personal access token). This enables additional catalog and entity tools. Find this in your DX account settings.

Usage

After saving the configuration, restart your AI client. You should see "dx-mcp" in the available MCP servers. When you ask questions about your data or catalog, the AI will use these tools to query your database or hit the relevant web apis.

---

Troubleshooting

Path Resolution Issues

The most common issue involves the MCP client not finding the dx-mcp-server/uv command, as GUI applications don't inherit the same PATH environment variables as the terminal. The solution is to use the full path to the executable in the json config.

For pip/pipx installations:

Find the full path to dx-mcp-server:

# Find the path on macOS/Linux
which dx-mcp-server

# Find the path on Windows (in Command Prompt)
where dx-mcp-server

Then use the full path in your configuration:

{
  "mcpServers": {
    "dx-mcp": {
      "command": "/full/path/to/dx-mcp-server",
      "args": ["run"],
      "env": {
        "DB_URL": "YOUR-DATABASE-URL",
        "WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
      }
    }
  }
}

For source installations:

Find the full path to uv:

# Find the path on macOS/Linux
which uv

# Find the path on Windows (in Command Prompt)
where uv

Then use the full path in your configuration:

{
  "mcpServers": {
    "dx-mcp": {
      "command": "/full/path/to/uv",
      "args": ["--directory", "/absolute/path/to/dx-mcp-server", "run", "-m", "dx_mcp_server", "run"],
      "env": {
        "DB_URL": "YOUR-DATABASE-URL",
        "WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
      }
    }
  }
}

Checking Logs

If you're still experiencing issues:

• Claude Desktop: Check logs at:

  • macOS: ~/Library/Logs/Claude/
  • Windows: %APPDATA%\Claude\logs\

• Cursor: Check logs at:

  • macOS: ~/Library/Application Support/Cursor/logs/[SESSION_ID]
  • Windows: %APPDATA%\Cursor\logs\[SESSION_ID]

The logs will show warning and error messages when starting or running the MCP server.