# 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](https://modelcontextprotocol.io/), 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`](/treasure-code/commands/claude) instead, which provides a more integrated experience with TD-specific skills and documentation search.

## Usage


```bash
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:


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

Without global install (using npx):


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

To use a specific profile:


```json
{
  "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:**


```json
{
  "args": ["databases"]
}
```

**Examples:**


```json
// 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:**


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

**Categories:** Data, CDP, AI, Context, Utilities

**Examples:**


```json
// 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
- `--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`.