AI/MCP Setup

TrailStack exposes the ClickHouse HTTP interface. The official ClickHouse MCP server (@clickhouse/mcp-server) lets AI assistants query your data in plain English.

Prerequisites

• A TrailStack Space with data (see Getting Started).
• Node.js 18+ installed.
• ClickHouse credentials from your Space: endpoint, database, username, password.

Step 1: Install

No global install needed. npx runs the MCP server directly:

npx -y @clickhouse/mcp-server

Step 2: Configure for Claude Desktop

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trailstack": {
      "command": "npx",
      "args": ["-y", "@clickhouse/mcp-server"],
      "env": {
        "CLICKHOUSE_HOST": "https://api.trailstack.io",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "<your-clickhouse-username>",
        "CLICKHOUSE_PASSWORD": "<your-clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<your-clickhouse-database>"
      }
    }
  }
}

Replace the placeholder values with the credentials from your Space. You can find them in the Connection details section on your Space page.

Step 3: Configure for Cursor

Add the same MCP config to Cursor. Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "trailstack": {
      "command": "npx",
      "args": ["-y", "@clickhouse/mcp-server"],
      "env": {
        "CLICKHOUSE_HOST": "https://api.trailstack.io",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "<your-clickhouse-username>",
        "CLICKHOUSE_PASSWORD": "<your-clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<your-clickhouse-database>"
      }
    }
  }
}

Step 4: Verify

1. Restart Claude Desktop or Cursor.
2. Ask: "Show me the tables in my database."
3. Expected: the assistant lists your views — all_events, all_errors, and event-specific views (e.g., evt_page_view).

If tables appear, the connection is working.

Example Query

Ask your AI assistant:

Show me the top 10 most frequent events in the last 24 hours.

Expected: the assistant runs a query like:

SELECT event_name, count()
FROM all_events
WHERE time > now() - INTERVAL 24 HOUR
GROUP BY event_name
ORDER BY count() DESC
LIMIT 10

The results come from your live TrailStack data via the ClickHouse HTTP interface.

Troubleshooting

Connection refused

• Verify the endpoint URL includes https:// and uses port 8443.
• Check that your network allows outbound connections to api.trailstack.io:8443.

Authentication error

• Verify username and password match the credentials from your Space.
• Credentials are shown once at Space creation. If lost, issue new credentials from the Space page.

No tables found

• Verify data was ingested and transformation completed. See Getting Started, step 5.
• Transformation typically takes about a minute after the first event.

MCP server not detected

• Restart Claude Desktop or Cursor after editing the config file.
• Verify the JSON syntax is valid (no trailing commas, matching braces).
• Verify Node.js 18+ is installed: node --version.