Installation and Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• pyproject.toml
• stacklet/mcp/stacklet_auth.py
• stacklet/mcp/settings.py
• stacklet/mcp/utils/mcp_json.py
• stacklet/mcp/cmdline.py

The Stacklet MCP Server provides tools for Large Language Models (LLMs) to interact with the Stacklet platform, including AssetDB SQL queries, Platform GraphQL operations, and documentation access. Successful setup requires installing the Python package, authenticating with a Stacklet environment, and configuring server behavior via environment variables or agent-specific profiles.

Sources: README.md:1-10, CLAUDE.md:8-15

Core Installation

The Stacklet MCP server is a Python-based application requiring Python 3.12 or higher. You can install the stacklet-mcp binary using standard Python package managers.

1. Install via pip:

   pip install stacklet-mcp
   

2. Or install via uv:

   uv tool install stacklet-mcp
   

Sources: README.md:23-31, pyproject.toml:13

Authentication Flow

The server requires valid Stacklet credentials to function. It resolves credentials through environment variables or local configuration files managed by the stacklet-admin tool.

Credential Resolution Logic

The system follows a specific priority when searching for authentication data:

1. Environment Variables: Checks STACKLET_ENDPOINT, STACKLET_ACCESS_TOKEN, and STACKLET_IDENTITY_TOKEN.
2. Local Config Files: Checks the ~/.stacklet/ directory for config.json (endpoint), credentials (access token), and id (identity token).

The following diagram illustrates the authentication resolution process:

The diagram shows how load_stacklet_auth prioritizes environment variables before falling back to filesystem-based configuration.

Sources: stacklet/mcp/stacklet_auth.py:46-95, CLAUDE.md:65-72

Using stacklet-admin

For the easiest setup, use the stacklet-admin CLI to manage your session:

1. Install the platform client: uv tool install stacklet.client.platform
2. Log in to your environment: stacklet-admin login

Sources: README.md:43-52

Server Configuration

Configure server behavior using environment variables prefixed with STACKLET_MCP_.

Variable	Description	Default
STACKLET_MCP_DOWNLOADS_PATH	Directory for storing query result files	System temp directory
STACKLET_MCP_DOWNLOADS_ENABLED	Whether to write result files to disk	true
STACKLET_MCP_ASSETDB_DATASOURCE_NAME	Name of AssetDB source in Redash	AssetDB
STACKLET_MCP_ASSETDB_ALLOW_SAVE	Enables assetdb_query_save tool	false
STACKLET_MCP_ASSETDB_ALLOW_ARCHIVE	Enables assetdb_query_archive tool	false
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS	Allows GraphQL mutations	false

Sources: README.md:60-72, CLAUDE.md:120-135, stacklet/mcp/settings.py

Agent Configuration Profiles

The server includes a command to generate .mcp.json configuration files for MCP clients like Claude Desktop. These profiles define the tools enabled and the environment settings.

Profile Types

• Default: Safe profile with write operations and mutations disabled.
• Unrestricted: Full access profile with all tools and mutations enabled.

Generating Configuration

Run the following command to generate the configuration:

stacklet-mcp agent-config generate [default|unrestricted]

The diagram shows how the agent-config command maps profiles to specific environment configurations in the generated JSON.

Sources: stacklet/mcp/utils/mcp_json.py:20-33, README.md:33-40, CLAUDE.md:185-195

Development Environment Setup

For developers contributing to the codebase, follow these steps to set up a local environment:

1. Tooling: Install Mise and run mise install.
2. Dependencies: Use just for task management:

   just install
   

3. Execution: Run the server locally:

   uv run stacklet-mcp
   # or
   just run
   

Sources: CLAUDE.md:74-88, README.md:86-105

Dependency Groups

The project uses uv for dependency management with specific groups defined in pyproject.toml.

• Main: fastmcp, graphql-core, httpx, pydantic.
• Dev: pytest, ruff, mypy, pre-commit.

Sources: pyproject.toml:23-45

Conclusion

Installation of the Stacklet MCP Server involves deploying the Python package and establishing a secure connection to the Stacklet platform via stacklet-admin. Configuration is primarily managed through environment variables or generated agent profiles, allowing administrators to scope LLM capabilities between read-only exploration and full administrative mutations.

Sources: README.md:12-20, CLAUDE.md:10-15