Application Context and Lifespan
Relevant source files
The following files were used as context for generating this wiki page:
The Stacklet MCP Server manages application context and lifespan to provide stable, authenticated access to cloud governance tools. The system uses FastMCP context to handle lazy initialization of clients and manage the lifecycle of connections to Stacklet's Platform GraphQL API and AssetDB SQL warehouse.
Lifespan management ensures that resources like authentication tokens, schema caches, and database connections remain valid throughout the session. The server utilizes a modular architecture where different packages (Platform, AssetDB, Docs) interact with a shared context to retrieve credentials and configuration settings.
Sources: [CLAUDE.md:12-24], [CLAUDE.md:66-70], [README.md:1-10]
Client Initialization and Caching
The server employs a .get(ctx) pattern for lazy initialization of service clients. This pattern ensures that clients for AssetDB and the Platform are only created when needed and are cached within the FastMCP context for the duration of the session.
Platform Client Lifecycle
The PlatformClient implements instance-level caching for GraphQL schemas. This prevents repeated introspection queries, which are computationally expensive and increase latency. The client loads credentials once per session using the StackletCredentials.get(ctx) method.
The diagram shows the lazy initialization flow for the Platform client, ensuring schema introspection happens once.
Sources: [CLAUDE.md:66-70], [CLAUDE.md:79-82], [stacklet/mcp/platform/tools.py:84-85]
AssetDB Client Lifecycle
The AssetDBClient manages connections to the Redash API. It handles long-running SQL queries through an asynchronous polling mechanism. When a query is executed, the client monitors the job status (Queued, Started, Finished) within the context of the requested timeout.
Sources: [CLAUDE.md:88-93], [stacklet/mcp/assetdb/tools.py:192-195], [stacklet/mcp/assetdb/models.py:27-37]
Lifespan and State Management
Application lifespan management is handled via stacklet/mcp/lifespan.py. This component coordinates the setup and teardown of shared resources.
Connection and Data States
The server tracks the state of asynchronous operations, specifically for large dataset exports and SQL jobs.
| Component | State Tracking | Resource Management |
|---|---|---|
| AssetDB Jobs | JobStatus (IntEnum) | Tracks terminal states: Finished, Failed, Canceled |
| Platform Exports | ConnectionExport | Manages dataset_id and download_url with 24hr expiry |
| Schema Cache | Instance-level cache | Persists within the PlatformClient lifecycle |
| Downloads | SETTINGS.downloads_path | Manages persistent local files or ephemeral resources |
Sources: [stacklet/mcp/assetdb/models.py:27-40], [stacklet/mcp/platform/tools.py:202-212], [stacklet/mcp/assetdb/tools.py:269-278], [CLAUDE.md:104-106]
Authentication Context
Authentication credentials resolution follows a hierarchical flow similar to the Stacklet Terraform provider. The context maintains these credentials for twelve hours after a successful login.
- Environment Variables:
STACKLET_ENDPOINT,STACKLET_ACCESS_TOKEN,STACKLET_IDENTITY_TOKEN. - Config Files: Located in
~/.stacklet/(e.g.,config.json,credentials,id).
The identity_token is specifically required for AssetDB access to handle Redash authentication cookies.
Sources: [CLAUDE.md:54-61], [README.md:46-55]
Execution Context and Configuration
The execution context is modified by feature flags and environment settings. These settings determine which tools are registered during the application startup lifespan.
The sequence shows how server settings dynamically configure the toolset during the application initialization phase.
Sources: [stacklet/mcp/assetdb/tools.py:42-50], [stacklet/mcp/platform/tools.py:35-47], [tests/test_settings.py:19-32]
Summary
Application Context and Lifespan in the Stacklet MCP server provide a managed environment for executing cloud governance tasks. By utilizing lazy initialization and schema caching within the FastMCP context, the server minimizes redundant network calls. The lifespan management ensures that authentication remains valid and that temporary resources, such as query results and dataset exports, are handled according to server configuration (local storage vs. embedded resources).
Sources: [CLAUDE.md:66-70], [stacklet/mcp/assetdb/tools.py:269-278]