Platform GraphQL Operations
Relevant source files
The following files were used as context for generating this wiki page:
Platform GraphQL Operations enable direct interaction with the Stacklet Platform for cloud governance, resource management, and compliance tracking. The system exposes a set of Model Context Protocol (MCP) tools that allow users and LLMs to introspect the platform schema, execute queries or mutations, and export large-scale datasets.
The core of this system is the PlatformClient, which manages authentication, schema caching, and API communication. It integrates with the FastMCP framework to provide structured access to governance data such as policies, account groups, and resource execution results.
Sources: stacklet/mcp/platform/graphql_info.md:3-5, stacklet/mcp/platform/graphql.py:38-55, CLAUDE.md:20-25
Architecture and Data Flow
The architecture follows a modular pattern where the PlatformClient acts as the primary interface between the MCP server and the Stacklet GraphQL API. The client implements instance-level caching for the GraphQL schema to improve performance and ensure query validity before transmission.
Request Execution Flow
When a GraphQL tool is called, the system performs local syntax parsing and schema validation before sending the request to the Stacklet endpoint.
This diagram illustrates the validation steps taken by the PlatformClient before an HTTP request is dispatched.
Sources: stacklet/mcp/platform/graphql.py:73-108, CLAUDE.md:120-125
Authentication
The client utilizes StackletCredentials to obtain a Bearer token. Every request includes the Authorization header and a custom X-Stacklet-MCP header for identification.
Sources: stacklet/mcp/platform/graphql.py:46-55
Core GraphQL Tools
The platform provides specific tools for schema exploration and data retrieval.
| Tool Name | Action | Read-Only |
|---|---|---|
platform_graphql_list_types | Lists available types using regex filtering. | Yes |
platform_graphql_get_types | Retrieves full SDL definitions for specific types. | Yes |
platform_graphql_query | Executes arbitrary GraphQL queries or mutations. | Conditional |
platform_graphql_info | Provides best practices and schema patterns. | Yes |
Sources: stacklet/mcp/platform/tools.py:27-41, stacklet/mcp/platform/graphql_info.md:32-35
Schema Introspection
To build correct queries, you must first discover types and their fields. The platform_graphql_get_types tool returns the GraphQL Schema Definition Language (SDL), which includes arguments and relationships.
Sources: stacklet/mcp/platform/tools.py:92-114, stacklet/mcp/platform/graphql.py:151-171
Query Best Practices
- Query Problems: Always include the
problemsfield in connection queries to capture critical metadata. Note thatproblemsobjects only contain amessagefield. - Pagination: Use
PageInfo.totalfor counts rather thantotalCount. Keep page sizes small (5-10 items) for exploration. - Filters: Query
filterSchemato understand availableFilterElementInputoptions.
Sources: stacklet/mcp/platform/graphql_info.md:10-22
Dataset Export System
For large-scale data analysis (typically 10,000+ records), the platform provides an asynchronous export system. This avoids the timeouts associated with deep pagination in standard GraphQL connections.
Export Workflow
The sequence shows the transition from the initial export request to the final retrieval of a download URL.
Sources: stacklet/mcp/platform/tools.py:175-212, stacklet/mcp/platform/graphql.py:173-206, stacklet/mcp/platform/dataset_info.md:65-68
Export Configuration
Exports require a list of ExportColumn objects. Each column defines a path (relative to the connection node) and an optional subpath for JMESPath transformations on JSON fields.
{
"name": "env_tag",
"path": "data",
"subpath": "Tags[?Key=='Environment'].Value | [0]"
}
Sources: stacklet/mcp/platform/models.py:90-107, stacklet/mcp/platform/dataset_info.md:30-36
Security and Mutations
By default, mutations are disabled to prevent accidental infrastructure changes.
- Mutation Control: The environment variable
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONSmust be set totrueto enable operations likeaddUserordeployBinding. - System Entities: Entities where the
systemfield istruecannot be mutated. - LLM Identity: When updating descriptions, you should document your identity and append context rather than replacing existing text.
Sources: stacklet/mcp/platform/tools.py:53-62, stacklet/mcp/platform/graphql_info.md:27-30, stacklet/mcp/settings.py
Summary of Data Models
ConnectionExport Status
| Field | Description |
|---|---|
dataset_id | Unique ID for the export job. |
processed_rows | Number of rows exported so far. |
success | Final status of the export operation. |
download_url | S3 redirect link for the CSV file. |
available_until | Timestamp for link expiry (typically 24 hours). |
Sources: stacklet/mcp/platform/models.py:141-158, stacklet/mcp/platform/dataset_info.md:69-72
Platform GraphQL Operations provide a robust interface for cloud governance. By combining real-time introspection with asynchronous large-scale exports, the system ensures that governance data remains accessible and actionable while maintaining strict validation and security controls.