High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Stacklet MCP Server provides a standardized Model Context Protocol interface for interacting with the Stacklet cloud governance platform. It exposes toolsets for documentation access, GraphQL-based governance operations, and SQL-based asset analytics. The server follows a modular design, separating logic into domain-specific packages for Docs, Platform, and AssetDB.
Sources: CLAUDE.md:1-12, README.md:1-8
System Overview
The architecture acts as a bridge between MCP clients (such as Claude Desktop or Claude Code) and three primary Stacklet backends. It translates natural language tool calls into structured API requests while managing authentication, pagination, and data formatting.
The diagram above illustrates the request flow from the client through the server's modular packages to the respective Stacklet backend services.
Sources: CLAUDE.md:14-38, README.md:10-14
Core Components
1. Server Lifecycle and CLI
The server utilizes the FastMCP framework to manage tool registration and request handling. A CLI interface, implemented in stacklet.mcp.cmdline, generates agent configurations and manages the application lifespan via stacklet.mcp.lifespan.
Sources: CLAUDE.md:16-22, stacklet/mcp/utils/mcp_json.py:38-66
2. Domain Packages
The codebase organizes functionality into three specialized packages:
| Package | Purpose | Primary Technologies |
|---|---|---|
| Docs | Provides read-only access to Stacklet documentation. | HTTP, Markdown |
| Platform | Manages governance operations via GraphQL. | graphql-core, Pydantic |
| AssetDB | Executes complex SQL analytics on cloud resources. | Redash API, SQL |
Sources: CLAUDE.md:24-40, stacklet/mcp/platform/tools.py:19-33, stacklet/mcp/assetdb/tools.py:27-42
3. Client Management
Both PlatformClient and AssetDBClient use a lazy initialization pattern. Clients are cached in the FastMCP context to optimize performance across multiple tool calls within a single session.
Sources: CLAUDE.md:112-115, stacklet/mcp/assetdb/redash.py:53-61
AssetDB Architecture
The AssetDB package enables SQL analysis of cloud resources. It interacts with the Stacklet AssetDB via the Redash API, supporting both synchronous and asynchronous execution patterns.
SQL Execution Flow
When a query takes longer than a standard response window, the server transitions to an asynchronous polling mechanism.
This sequence diagram shows the transition from a query request to job polling for long-running AssetDB operations.
Sources: stacklet/mcp/assetdb/redash.py:177-226, stacklet/mcp/assetdb/tools.py:186-218
Result Handling
To prevent context overflow in LLMs, the server limits inline row results to 20 rows. It handles the remaining data based on the STACKLET_MCP_DOWNLOADS_ENABLED setting:
- Enabled: Writes a JSON file to the local filesystem.
- Disabled: Attaches the data as an
EmbeddedResource(MCP Resource) to the response.
Sources: stacklet/mcp/assetdb/tools.py:269-322, stacklet/mcp/assetdb/models.py:202-232
Platform Architecture
The Platform package facilitates governance through GraphQL. It implements instance-level schema caching to avoid repeated introspection queries, which improves performance for large-scale operations.
GraphQL Integration Features
- Schema Discovery: Tools like
platform_graphql_list_typesandplatform_graphql_get_typesallow clients to inspect the API structure dynamically. - Dataset Export: For datasets exceeding typical connection page limits, the
platform_dataset_exporttool triggers server-side CSV generation. - Mutation Safety: Mutations are disabled by default and require explicit environment configuration (
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS=true).
Sources: stacklet/mcp/platform/tools.py:51-140, stacklet/mcp/platform/models.py:90-128, CLAUDE.md:120-130
Authentication and Security
The server replicates the Stacklet Terraform provider's credential resolution hierarchy.
Authentication Flow
- Environment Variables: Checks for
STACKLET_ENDPOINT,STACKLET_ACCESS_TOKEN, andSTACKLET_IDENTITY_TOKEN. - Local Config: Reads from
~/.stacklet/config.jsonand~/.stacklet/credentials.
Sources: CLAUDE.md:42-50, README.md:50-65
Security Profiles
The server supports two primary configuration profiles defined in stacklet.mcp.utils.mcp_json:
| Profile | Permissions | Default Behavior |
|---|---|---|
| Default | Read-Only | Disables assetdb_allow_save, assetdb_allow_archive, and platform_allow_mutations. |
| Unrestricted | Read/Write | Enables all write operations and mutations. |
Sources: stacklet/mcp/utils/mcp_json.py:17-31, README.md:37-45
Summary
The Stacklet MCP Server provides a modular, secure interface for LLMs to access governance documentation, GraphQL APIs, and SQL analytics. By implementing lazy client initialization, schema caching, and asynchronous job polling, the architecture ensures efficient communication with Stacklet backends while maintaining strict security boundaries via configurable permission profiles.
Sources: CLAUDE.md:14-50, stacklet/mcp/assetdb/redash.py:53-61