FastMCP Integration
Relevant source files
The following files were used as context for generating this wiki page:
Stacklet MCP Server integrates with the FastMCP framework to expose Stacklet platform capabilities to Large Language Models (LLMs). The server functions as a factory that aggregates specialized toolsets for cloud asset analytics, governance operations, and documentation access.
The integration utilizes FastMCP's tool decorator patterns, context management, and lifespan protocols to maintain state across client sessions while enforcing security through feature flags and credential resolution.
Sources: CLAUDE.md:12-20, stacklet/mcp/server.py:46-60
Server Architecture and Lifecycle
The server entry point is managed by make_server, which initializes a FastMCP instance. This instance acts as the orchestrator for tool registration and lifespan management.
Component Diagram
The following diagram illustrates the relationship between the FastMCP server, the aggregated toolsets, and the underlying state management.
The diagram shows how FastMCP centralizes tools and manages process-level state via lifespan protocols.
Sources: stacklet/mcp/server.py:46-70, CLAUDE.md:16-19
Core Components Summary
| Component | Description | Source File |
|---|---|---|
FastMCP | The main framework instance managing tools and MCP protocol communication. | server.py:65 |
make_lifespan | Manages the application lifecycle, including provider and state initialization. | server.py:69 |
LocalAuthProvider | Resolves credentials from environment variables or local config files. | server.py:62 |
ServerState | Provides process-lifetime caching for local stdio usage. | server.py:56 |
Tool Implementation and Decoration
Tools are implemented as Python functions decorated with metadata and type hints. The project uses a make_tool utility to wrap these functions with specific MCP annotations like readOnlyHint and destructiveHint.
Tool Definition Flow
This flow illustrates the registration of a standard Python function into the MCP ecosystem with behavioral hints.
Sources: stacklet/mcp/platform/tools.py:20-40, tests/testing/mcp.py:15-40
Feature-Flagged Tool Inclusion
The server dynamically enables or disables tools based on Settings. For example, AssetDB write operations and Platform mutations are conditionally registered based on environment configuration.
def _graphql_query_tool() -> Tool:
mutations = SETTINGS.platform_allow_mutations
return make_tool(
platform_graphql_query,
read_only=not mutations,
destructive=mutations,
)
Sources: stacklet/mcp/platform/tools.py:34-42, stacklet/mcp/server.py:64-68
Client Configuration and Profiles
The integration supports generating .mcp.json configuration files for MCP clients like Claude Desktop. These profiles define how the FastMCP server should be executed and what environment settings to apply.
Configuration Profiles
| Profile | Description | settings Enabled |
|---|---|---|
default | Restricted access. No edits allowed. | assetdb_allow_archive=False, platform_allow_mutations=False |
unrestricted | Full access. All tools enabled. | assetdb_allow_archive=True, platform_allow_mutations=True |
Sources: stacklet/mcp/utils/mcp_json.py:20-35, README.md:38-44
Environment Injection
FastMCP relies on environment variables for configuration. The server maps internal Pydantic settings to environment variables with the STACKLET_MCP_ prefix during execution.
Sources: stacklet/mcp/utils/mcp_json.py:59-68, stacklet/mcp/settings.py:15-30
Context and Resource Management
Tools use the fastmcp.Context object to access lazy-initialized clients (e.g., PlatformClient, RedashClient). This prevents unnecessary authentication calls until a tool actually requires them.
Data Flow for Tool Execution
- Request: The MCP Client calls a tool (e.g.,
platform_graphql_query). - Context Resolution: The tool retrieves the client via
PlatformClient.get(ctx). - Auth Loading:
PlatformClientrequests credentials fromStackletCredentials.get(ctx). - Execution: The tool performs the operation and returns a structured response.
- Resource Attachment: Large results (like SQL output) are either saved to disk or attached as an MCP resource if file downloads are disabled.
Sources: CLAUDE.md:70-75, stacklet/mcp/platform/tools.py:110-120, stacklet/mcp/settings.py:45-55
Conclusion
FastMCP Integration in this project provides a modular and secure bridge to Stacklet's cloud governance ecosystem. By using FastMCP's lifespan and context features, the server ensures efficient resource management and strict adherence to configured permission profiles. The use of MCP-specific annotations allows the server to communicate behavioral expectations directly to the LLM agent, enhancing safety and transparency.