Security Model
Relevant source files
The following files were used as context for generating this wiki page:
The Stacklet MCP Server security model governs how large language models (LLMs) access sensitive cloud governance data and execute operations. The system uses a multi-layered approach involving credential resolution, feature-based permission toggles, and tool-level annotations to manage risks associated with automated access to Stacklet environments.
Sources: README.md:12-20, CLAUDE.md:65-75
Authentication and Credential Management
The server inherits the Stacklet platform's authentication mechanisms. It requires three primary credentials to function across all components: an endpoint URL, an access token, and an identity token. The identity token is specifically required for AssetDB access via Redash authentication cookies.
Sources: CLAUDE.md:88-93, stacklet/mcp/assetdb/redash.py:46-51
Credential Resolution Priority
The stacklet_auth.py module resolves credentials using the following hierarchy:
- Environment Variables: Checks
STACKLET_ENDPOINT,STACKLET_ACCESS_TOKEN, andSTACKLET_IDENTITY_TOKEN. - Configuration Files: Reads from
~/.stacklet/config.json(endpoint),~/.stacklet/credentials(access token), and~/.stacklet/id(identity token).
Sources: CLAUDE.md:88-93, stacklet/mcp/stacklet_auth.py:65-95
Authentication Data Flow
The following sequence shows how credentials are loaded and applied to service clients:
Diagram based on authentication resolution logic in stacklet/mcp/stacklet_auth.py:65-95 and client usage in stacklet/mcp/assetdb/redash.py:46-51.
Feature Flags and Authorization
The server implements a "safe by default" stance. By default, the server operates in a read-only mode for governance data. Write operations and mutations must be explicitly enabled through configuration environment variables.
Sources: README.md:16-20, stacklet/mcp/settings.py:46-59
Configuration Controls
| Variable | Default | Security Impact |
|---|---|---|
STACKLET_MCP_ASSETDB_ALLOW_SAVE | false | Enables saving or updating SQL queries in Redash. |
STACKLET_MCP_ASSETDB_ALLOW_ARCHIVE | false | Enables query archiving (destructive operation). |
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS | false | Enables GraphQL mutations (updates/deletes) in the Platform API. |
STACKLET_MCP_DOWNLOADS_ENABLED | true | Controls whether results are written to the local filesystem. |
Sources: stacklet/mcp/settings.py:20-59, README.md:46-56
Tool-Level Security Annotations
The server uses FastMCP tool annotations to provide hints to MCP clients (like Claude Desktop) about the nature of the tools. These hints allow the client to prompt the user before executing potentially dangerous or wide-reaching operations.
Sources: stacklet/mcp/assetdb/tools.py:27-46, stacklet/mcp/platform/tools.py:27-43
Annotation Categories
- read_only: Indicates if the tool only retrieves data without modification.
- destructive: Indicates if the tool can delete or significantly alter data.
- open_world: Indicates if the tool accesses external or non-deterministic data sources.
Sources: stacklet/mcp/assetdb/tools.py:44-60, stacklet/mcp/platform/tools.py:46-54
Diagram based on tool initialization logic in stacklet/mcp/platform/tools.py:46-54 and stacklet/mcp/assetdb/tools.py:27-46.
Implementation Details
GraphQL Mutation Protection
In the platform package, the _graphql_query_tool function dynamically assigns security annotations based on the platform_allow_mutations setting. If disabled, the client is configured to reject mutation documents before they are sent to the API.
Sources: stacklet/mcp/platform/tools.py:46-54, stacklet/mcp/platform/graphql.py:170-175
Sensitive Data Scrubbing
The Query model in the AssetDB package is configured with extra="ignore". This ensures that sensitive fields like api_key, which Redash includes in query serializations, are dropped during parsing and are never leaked into logs, tool responses, or transcripts.
Sources: stacklet/mcp/assetdb/models.py:75-80
Download Security
Query results are handled differently based on the environment to prevent unauthorized filesystem accumulation or access:
- Local/Default: Results are written to a temporary directory defined by
downloads_path. - Hosted: Results are attached directly to the tool response as a resource, bypassing the server's local filesystem.
Sources: stacklet/mcp/settings.py:20-29, stacklet/mcp/assetdb/tools.py:257-270
Summary of Security Profiles
The server provides pre-defined agent configuration profiles to simplify security setup:
- default: A restricted profile with all write operations (
assetdb_allow_save,assetdb_allow_archive) and platform mutations (platform_allow_mutations) disabled. - unrestricted: Enables all tools and modifications.
Sources: CLAUDE.md:143-149, stacklet/mcp/utils/mcp_json.py:20-33