MCP Server

Start an MCP (Model Context Protocol) server that enables AI coding assistants to interact with Treasure Data.

Overview

The tdx mcp command exposes tdx functionality to AI tools that support the Model Context Protocol, including:

• Cursor - AI-powered code editor
• Windsurf - AI development environment
• VS Code - With GitHub Copilot or other MCP-compatible extensions
• Claude Desktop - Anthropic's desktop app
• Other MCP-compatible tools

Once configured, you can ask your AI assistant to query databases, manage segments, run workflows, and more - all through natural conversation.

For Claude Code Users

If you're using Claude Code, consider using tdx claude instead, which provides a more integrated experience with TD-specific skills and documentation search.

Usage

tdx mcp

The server runs on stdio transport and waits for MCP protocol messages.

Authentication

If tdx is already authenticated (via tdx auth setup), no additional configuration is needed. The MCP server uses your existing credentials automatically.

For advanced scenarios, authentication can be overridden via environment variables (in priority order):

1. TDX_PROFILE - Use a specific profile's credentials
2. TDX_API_KEY + TDX_SITE - Direct credentials
3. Default - Uses existing tdx authentication chain

Setup

Add the following to your AI tool's MCP configuration:

{
  "mcpServers": {
    "tdx": {
      "command": "tdx",
      "args": ["mcp"]
    }
  }
}

Without global install (using npx):

{
  "mcpServers": {
    "tdx": {
      "command": "npx",
      "args": ["@treasuredata/tdx", "mcp"]
    }
  }
}

To use a specific profile:

{
  "mcpServers": {
    "tdx": {
      "command": "tdx",
      "args": ["mcp"],
      "env": {
        "TDX_PROFILE": "my-profile"
      }
    }
  }
}

Configuration File Locations

Tool	Config File
Cursor	~/.cursor/mcp.json
Windsurf	~/.windsurf/mcp.json
VS Code	Depends on AI extension (see extension docs)
Claude Desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Refer to your tool's documentation for the exact configuration details.

Available Tools

tdx_run

Execute any tdx CLI command. Returns JSON output.

Input:

{
  "args": ["databases"]
}

Examples:

// List databases
{ "args": ["databases"] }

// Run SQL query
{ "args": ["query", "SELECT * FROM mydb.users LIMIT 10"] }

// List segments recursively
{ "args": ["segments", "--recursive"] }

// Show job details
{ "args": ["job", "show", "12345"] }

// List tables with pattern
{ "args": ["tables", "mydb.*"] }

tdx_search

Search for relevant tdx commands based on what you want to do.

Input:

{
  "query": "how to run SQL queries",
  "category": "Data"  // optional
}

Categories: Data, CDP, AI, Context, Utilities

Examples:

// Search for SQL-related commands
{ "query": "how to run SQL queries" }

// Search within CDP category
{ "query": "manage customer segments", "category": "CDP" }

// Search for workflow commands
{ "query": "workflow logs" }

Blocked Commands

For security, the following commands and flags are blocked via MCP:

• auth setup, auth clear - Credential management
• profile create, profile remove - Profile management
• mcp - Recursive MCP server
• llm proxy - Conflicts with MCP server
• --profile flag - Profile switching not allowed

Example Conversation

Once the MCP server is configured, you can ask your AI assistant:

> What databases are available in Treasure Data?

AI uses tdx_run with args: ["databases"]

> Show me the schema for the users table in mydb

AI uses tdx_run with args: ["describe", "mydb.users"]

> Run a query to find the top 10 users by order count

AI uses tdx_run with args: ["query", "SELECT user_id, COUNT(*) as orders FROM mydb.orders GROUP BY user_id ORDER BY orders DESC LIMIT 10"]

> Create a segment for users who made a purchase in the last 30 days

AI uses tdx_search to find segment commands, then tdx_run to create the segment

Troubleshooting

Server not starting

1. Ensure tdx is installed and in your PATH (or use npx/bunx)
2. Verify authentication is configured: tdx auth
3. Check logs: ~/.cache/tdx/logs/tdx.log

Authentication errors

1. Run tdx auth setup to configure credentials
2. Or set TDX_PROFILE to a valid profile name
3. Or set both TDX_API_KEY and TDX_SITE environment variables
4. Verify credentials work: tdx user

Commands timing out

Commands have a 15-minute timeout. For long-running operations (like large queries), consider using job submit instead of direct query.