Server Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Stacklet MCP Server uses a modular configuration system based on environment variables and predefined profiles. This system controls feature flags, file storage behavior, and authentication parameters across different governance toolsets including AssetDB and the Platform GraphQL API.
Server settings are managed via Pydantic's BaseSettings, allowing for type-safe validation and automatic loading from the environment using the STACKLET_MCP_ prefix.
Sources: stacklet/mcp/settings.py:16-19, README.md:57-61
Core Configuration Options
The server defines several key parameters that govern how it interacts with Stacklet infrastructure and handles local data.
Configuration Variables
| Variable | Type | Default | Description |
|---|---|---|---|
STACKLET_MCP_DOWNLOADS_PATH | Path | System Temp | Directory for storing query result files. |
STACKLET_MCP_DOWNLOADS_ENABLED | bool | True | Enables writing results to disk; disable for hosted environments. |
STACKLET_MCP_ASSETDB_DATASOURCE | int | None | Explicit Redash data source ID. |
STACKLET_MCP_ASSETDB_DATASOURCE_NAME | str | "AssetDB" | Name used to look up the data source ID if DATASOURCE is unset. |
STACKLET_MCP_ASSETDB_ALLOW_SAVE | bool | false | Enables tools for saving/updating AssetDB queries. |
STACKLET_MCP_ASSETDB_ALLOW_ARCHIVE | bool | false | Enables tools for archiving AssetDB queries. |
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS | bool | false | Enables GraphQL mutation operations. |
Sources: stacklet/mcp/settings.py:24-61, README.md:65-71, CLAUDE.md:144-154
Result Storage Logic
The downloads_enabled setting determines the data flow for large query results. If enabled, the server writes a JSON array to the local filesystem. If disabled, the server attaches the JSON array directly to the tool response as an MCP resource.
The diagram shows the decision logic for handling full query results based on server configuration.
Sources: stacklet/mcp/assetdb/tools.py:341-356, CLAUDE.md:156-163
Configuration Profiles
The server supports generating .mcp.json configuration files for clients like Claude Desktop using two distinct profiles: default and unrestricted.
- Default Profile: Disables all write operations. Sets
assetdb_allow_save,assetdb_allow_archive, andplatform_allow_mutationstofalse. - Unrestricted Profile: Enables all capabilities by setting all three flags to
true.
Sources: stacklet/mcp/utils/mcp_json.py:27-37, CLAUDE.md:195-201
Profile Implementation
MCP_SETTINGS_PROFILES = {
Profile.DEFAULT: Settings(
assetdb_allow_archive=False,
assetdb_allow_save=False,
platform_allow_mutations=False,
),
Profile.UNRESTRICTED: Settings(
assetdb_allow_archive=True,
assetdb_allow_save=True,
platform_allow_mutations=True,
),
}
Sources: stacklet/mcp/utils/mcp_json.py:27-37
Tool-Level Enforcement
Configuration flags directly influence which tools are registered by the server and how they behave.
AssetDB Tool Registration
The server dynamically populates the tool list based on the assetdb_allow_save and assetdb_allow_archive settings.
if SETTINGS.assetdb_allow_save:
tools.append(make_tool(assetdb_query_save, read_only=False, destructive=True))
if SETTINGS.assetdb_allow_archive:
tools.append(make_tool(assetdb_query_archive, read_only=False, destructive=True, idempotent=True))
Sources: stacklet/mcp/assetdb/tools.py:46-52
Platform Mutation Enforcement
For GraphQL, the platform_allow_mutations setting determines if the platform_graphql_query tool is marked as read_only or destructive. When disabled, the client rejects mutation documents before they reach the API.
Sources: stacklet/mcp/platform/tools.py:38-47
Authentication Configuration
Authentication requires three primary components typically resolved from the environment or local Stacklet configuration files.
| Configuration Item | Environment Variable | Config File Path |
|---|---|---|
| Endpoint | STACKLET_ENDPOINT | ~/.stacklet/config.json |
| Access Token | STACKLET_ACCESS_TOKEN | ~/.stacklet/credentials |
| Identity Token | STACKLET_IDENTITY_TOKEN | ~/.stacklet/id |
Sources: CLAUDE.md:132-140, README.md:41-47
Windows-Specific Configuration
On Windows systems, the PYTHONUTF8 environment variable is automatically set to 1 by the agent-config generator to prevent encoding errors at startup.
Sources: stacklet/mcp/utils/mcp_json.py:75-77, README.md:73-77
The Stacklet MCP server provides a flexible configuration framework that balances security and functionality. By using profiles and environment variables, administrators can scope the server's capabilities—from read-only documentation access to full governance mutation powers—to match specific user requirements and security policies.