AssetDB Redash Client Integration
Relevant source files
The following files were used as context for generating this wiki page:
The AssetDB Redash Client Integration provides a bridge between the MCP server and Stacklet's cloud resource data warehouse. It allows Model Context Protocol (MCP) tools to execute SQL queries, manage saved queries, and retrieve analytics data through the Redash API.
The system uses Stacklet authentication tokens to authorize requests against the Redash endpoint. It handles both synchronous and asynchronous query execution, providing LLMs with structured access to massive datasets across multiple cloud providers.
Sources: CLAUDE.md:32-34, stacklet/mcp/assetdb/redash.py:24-30
Architecture and Client Implementation
The AssetDBClient class serves as the central interface for all AssetDB operations. It manages an httpx.AsyncClient session configured with Stacklet identity tokens for authentication.
Core Components
- Client Factory: The
.get(ctx)method provides lazy initialization of the client within the FastMCP context. - Authentication: The client includes the
stacklet-authidentity token in request cookies. - Endpoint Derivation: The client derives the Redash URL by replacing the
api.prefix withredash.in the platform endpoint. - Session Management: A shared
AsyncHTTPTransportfacilitates efficient connection pooling across tool calls.
Sources: stacklet/mcp/assetdb/redash.py:32-68, CLAUDE.md:131-133
Class Relationships
The following diagram illustrates the relationship between the client, the models, and the Redash API states.
The client manages the lifecycle of queries and polls jobs to produce results.
Sources: stacklet/mcp/assetdb/redash.py:32-260, stacklet/mcp/assetdb/models.py:25-82
Data Source Management
Redash assigns unique IDs to data sources upon creation. The client must resolve the correct ID for the AssetDB instance to execute queries.
Resolution Logic
- If
STACKLET_MCP_ASSETDB_DATASOURCEis set, the client uses that ID directly. - If no ID is set, the client queries the
/api/data_sourcesendpoint. - The client filters results by the name provided in
STACKLET_MCP_ASSETDB_DATASOURCE_NAME(default: "AssetDB"). - Successful resolutions are cached for the process duration.
- Failed lookups are not cached to prevent temporary permission issues from causing persistent failures.
Sources: stacklet/mcp/assetdb/redash.py:70-120, README.md:57-60
Query Execution Flow
The integration supports both ad-hoc SQL execution and execution of existing saved queries.
Execution Process
Queries proceed through a multi-stage flow to handle long-running operations:
- Initiation: The client POSTs the query to the Redash API.
- Immediate Result: If the result is cached or short-lived, Redash returns the
query_resultobject directly. - Async Job: For new or long queries, Redash returns a
jobobject. - Polling: The client enters an asynchronous loop, polling the job status with exponential backoff.
- Retrieval: Once the job status reaches
FINISHED, the client fetches the result data using the result ID.
This flowchart shows the transition from a synchronous request to an asynchronous polling loop.
Sources: stacklet/mcp/assetdb/redash.py:185-245
Job Statuses
The client monitors these statuses defined in JobStatus:
| Status | Code | Terminal | Action |
|---|---|---|---|
| QUEUED | 1 | No | Continue Polling |
| STARTED | 2 | No | Continue Polling |
| FINISHED | 3 | Yes | Fetch Result |
| FAILED | 4 | Yes | Raise Execution Error |
| CANCELED | 5 | Yes | Raise Execution Error |
Sources: stacklet/mcp/assetdb/models.py:25-37
MCP Tool Integration
Tools in stacklet/mcp/assetdb/tools.py wrap client methods to expose functionality to the MCP server.
Available Tool Types
- Ad-hoc SQL:
assetdb_sql_queryexecutes raw SQL strings. It applies an auto-limit to prevent context overflow. - Saved Queries:
assetdb_query_resultruns stored queries by ID. It supports parameters using the{{param}}syntax. - Management:
assetdb_query_list,assetdb_query_get,assetdb_query_save, andassetdb_query_archiveallow full CRUD operations on query metadata.
Sources: stacklet/mcp/assetdb/tools.py:27-50, stacklet/mcp/assetdb/sql_info.md:66-70
Configuration Parameters
The integration behavior is controlled by several environment variables:
| Variable | Default | Purpose |
|---|---|---|
STACKLET_MCP_ASSETDB_ALLOW_SAVE | false | Enables the assetdb_query_save tool. |
STACKLET_MCP_ASSETDB_ALLOW_ARCHIVE | false | Enables the assetdb_query_archive tool. |
STACKLET_MCP_DOWNLOADS_ENABLED | true | Writes full results to disk as JSON files. |
STACKLET_MCP_DOWNLOADS_PATH | Temp Dir | Directory for result file storage. |
Sources: README.md:55-63, stacklet/mcp/assetdb/tools.py:343-356
Result Handling and Pagination
To maintain LLM efficiency, the integration applies specific handling to query results.
- Truncation: Tools return only the first 20 rows of a result set to the LLM context.
- Full Results: The complete dataset is provided via a local file path if
downloads_enabledis true, or attached as a JSON resource. - Formats: For saved queries, the client generates download URLs for
CSV,JSON,TSV, andXLSXformats. - Security: The query's Redash API key is stripped from all responses to prevent credential leakage.
Sources: stacklet/mcp/assetdb/tools.py:382-415, stacklet/mcp/assetdb/models.py:53-58, stacklet/mcp/assetdb/redash.py:248-265
Summary
The AssetDB Redash Client Integration enables robust SQL-based cloud resource analysis. It leverages Redash's query execution engine while providing specialized handling for MCP environments, including async polling, result truncation, and secure credential management. By default, it operates in a read-only mode, but it can be configured to allow full query lifecycle management.