Authentication Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication Flow manages the resolution and distribution of Stacklet credentials to various service clients within the MCP server. It implements a tiered resolution strategy that echoes the Stacklet Terraform provider, ensuring the server can access the Platform GraphQL API, AssetDB, and Documentation services.
Authentication is mandatory for the server to function. Users typically obtain credentials by logging in via the stacklet-admin CLI tool, which grants access for a twelve-hour duration. The server then loads these credentials from local configuration files or environment variables to authenticate its outgoing HTTP requests.
Sources: README.md:46-59, CLAUDE.md:42-45
Credential Components
The system requires three specific credential fields for full functionality across all toolsets.
| Field | Description | Requirement |
|---|---|---|
endpoint | The base URL for the Stacklet Platform API. | Required for all operations. |
access_token | A Bearer token used for GraphQL and Documentation API calls. | Required for Platform and Docs. |
identity_token | A token used to establish Redash authentication sessions. | Required for AssetDB SQL access. |
Sources: CLAUDE.md:129-130, stacklet/mcp/stacklet_auth.py:20-25, stacklet/mcp/assetdb/redash.py:46
Authentication Architecture
The architecture utilizes an AuthProvider protocol to abstract how credentials are retrieved. In standard local deployments, the LocalAuthProvider resolves credentials using a specific priority order.
The diagram shows the flow from a tool request to the resolution of credentials and their distribution to service clients.
Sources: stacklet/mcp/server.py:24-40, CLAUDE.md:42-45, stacklet/mcp/stacklet_auth.py:59-70
Credential Resolution Logic
The load_stacklet_auth function performs the resolution. It prioritizes environment variables over files stored in the user's home directory.
1. Environment Variables
The system checks for the following variables:
STACKLET_ENDPOINTSTACKLET_ACCESS_TOKENSTACKLET_IDENTITY_TOKEN
Sources: CLAUDE.md:43, stacklet/mcp/stacklet_auth.py:65-68
2. Local Configuration Files
If environment variables are missing, the server looks in the ~/.stacklet directory for the following files:
config.json: Contains theapiendpoint URL.credentials: Contains the access token string.id: Contains the identity token string.
Sources: CLAUDE.md:44-45, stacklet/mcp/stacklet_auth.py:82-95
Service Endpoint Derivation
Clients use the base platform endpoint to derive specific service URLs for Redash (AssetDB) and Documentation services.
This diagram illustrates how the single configured endpoint is transformed to reach different Stacklet services.
Sources: CLAUDE.md:120-123, stacklet/mcp/stacklet_auth.py:44-56
Implementation in Service Clients
Once resolved, credentials are used differently depending on the target service's authentication requirements.
Platform and Documentation Auth
These services use standard HTTP Authorization headers.
- Header:
Authorization: Bearer <access_token> - Identification: The
X-Stacklet-MCP: 1header is also sent to identify the client.
Sources: tests/test_tools_platform.py:539-546
AssetDB (Redash) Auth
AssetDB requires the identity_token passed as a cookie to maintain a session.
- Cookie:
stacklet-auth=<identity_token>
Sources: stacklet/mcp/assetdb/redash.py:46, CLAUDE.md:46
Security and Error Handling
The authentication flow includes safeguards to prevent credential leakage and handle missing information:
- Credential Security: Access and identity tokens are explicitly excluded from logs and error messages.
- Validation: If any of the three required components (endpoint, access_token, identity_token) are missing after resolution, the system raises a
ValueErrorindicating exactly which fields are absent. - Lazy Initialization: Clients use a
.get(ctx)pattern to load credentials only when a tool is actually invoked.
Sources: CLAUDE.md:95-97, stacklet/mcp/stacklet_auth.py:102-105, stacklet/mcp/assetdb/redash.py:50-58
Summary
The Authentication Flow ensures that the MCP server operates with the same permissions and scope as the authenticated Stacklet user. By resolving credentials from standardized environment variables and local files, it provides a seamless experience for users already utilizing the stacklet-admin toolset while maintaining strict isolation of sensitive tokens from system logs.