Project Introduction
Relevant source files
The following files were used as context for generating this wiki page:
The Stacklet MCP Server implements the Model Context Protocol (MCP) to provide Large Language Models (LLMs) with tools for interacting with the Stacklet environment. It exposes toolsets for cloud governance operations, asset analytics via SQL, and access to live documentation.
Sources: README.md:1-8, CLAUDE.md:6-10
Architecture Overview
The server follows a modular design that separates core logic from specific Stacklet service integrations. It uses the FastMCP framework to define and expose tools to MCP-compliant clients like Claude Desktop.
Sources: CLAUDE.md:12-14
Core Components
The project organizes functionality into the following core areas:
- Server Core: Manages the FastMCP instance, CLI integration, and application lifespan.
- Authentication: Resolves credentials from environment variables and local Stacklet configuration files.
- Specialized Packages:
docs: Fetches and reads Markdown documentation from Stacklet deployments.platform: Interfaces with the Stacklet Platform GraphQL API.assetdb: Executes SQL queries against the Stacklet Asset Database via Redash.
Sources: CLAUDE.md:16-41
System Data Flow
The diagram below illustrates how an LLM request flows through the MCP server to the Stacklet backend services.
The server acts as a bridge, translating high-level tool calls into specific API requests against governance and analytics endpoints.
Sources: CLAUDE.md:43-52, README.md:4-8
Core Toolsets
The server provides three primary toolsets. Each includes an info tool that provides context and best practices for that specific domain.
Sources: README.md:10-14, stacklet/mcp/mcp_info.md:5-10
1. AssetDB SQL Analytics
This toolset allows analysis of multi-cloud estates using a PostgreSQL warehouse. It supports ad-hoc SQL queries and management of saved queries.
| Tool Name | Action | Description |
|---|---|---|
assetdb_sql_info | Read | Essential guidance for LLMs using SQL tools. |
assetdb_sql_query | Execute | Runs ad-hoc SQL against the cloud asset warehouse. |
assetdb_query_list | List | Searches saved queries with pagination support. |
assetdb_query_result | Execute | Retrieves results for saved queries with caching. |
Sources: CLAUDE.md:83-92, stacklet/mcp/assetdb/tools.py:46-55
2. Platform GraphQL Governance
These tools manage governance policies, account discovery, and compliance monitoring through the Stacklet Platform API.
| Tool Name | Action | Description |
|---|---|---|
platform_graphql_info | Read | Guidance for GraphQL schema and query patterns. |
platform_graphql_query | Execute | Runs queries or mutations against the platform. |
platform_dataset_export | Export | Triggers large-scale CSV exports of connections. |
platform_graphql_list_types | Inspect | Discovers available types in the GraphQL schema. |
Sources: CLAUDE.md:73-81, stacklet/mcp/platform/tools.py:22-35
3. Documentation Access
This toolset provides live access to Stacklet's documentation, including how-to guides and reference materials for both the core platform and IaC Governance (Sinistral).
Sources: stacklet/mcp/mcp_info.md:38-43, CLAUDE.md:70-71
Configuration and Security
The server utilizes environment variables for configuration and relies on standard Stacklet credential resolution.
Server Settings
Users can control server behavior and safety limits through environment variables prefixed with STACKLET_MCP_.
| Variable | Default | Purpose |
|---|---|---|
STACKLET_MCP_ASSETDB_ALLOW_SAVE | false | Enables creating or updating saved queries. |
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS | false | Enables write operations in the Platform API. |
STACKLET_MCP_DOWNLOADS_ENABLED | true | Writes large query results to local disk. |
STACKLET_MCP_DOWNLOADS_PATH | Temp Dir | Directory for storing result files. |
Sources: README.md:47-60, CLAUDE.md:121-131
Authentication Flow
The server resolves credentials in a specific order, mimicking the Stacklet Terraform provider.
Sources: CLAUDE.md:54-61, README.md:33-43
Technical Implementation Details
Result Handling
For AssetDB and Platform exports, the server manages large datasets by truncating inline responses and providing full results through external routes.
- Inline Sample: Tools like
assetdb_sql_queryreturn only the first 20 rows to keep LLM context compact. - Full Data: If
downloads_enabledis true, the server writes the full JSON array to a local file. If disabled, the server attaches the data as an MCPresource.
Sources: stacklet/mcp/assetdb/tools.py:269-282, stacklet/mcp/assetdb/models.py:254-266
Schema Caching
The PlatformClient implements instance-level caching for GraphQL introspection. This avoids repeated expensive queries when the LLM explores available types or fields.
Sources: CLAUDE.md:104-106, stacklet/mcp/platform/tools.py:86-95
Conclusion
The Stacklet MCP Server provides a specialized interface for LLMs to perform cloud governance and asset analysis. By exposing structured tools for GraphQL, SQL, and documentation, it enables agents to automate discovery, compliance monitoring, and reporting within the Stacklet ecosystem while maintaining security through configurable feature flags and standard authentication.
Sources: README.md:1-8, stacklet/mcp/mcp_info.md:1-3