Platform GraphQL Client Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Platform GraphQL Client Integration provides a structured interface for interacting with the Stacklet Platform's governance API. It enables Model Context Protocol (MCP) clients to explore schema types, execute queries, perform mutations, and manage large-scale dataset exports. The integration focuses on safety through local schema validation and performance via instance-level schema caching.
This system serves as the primary gateway for governance operations, including managing policies, account groups, bindings, and resource compliance. For high-volume data analysis beyond the scope of GraphQL connection limits, the integration provides specialized tools for asynchronous CSV exports.
Sources: stacklet/mcp/platform/graphql.py:27-30, stacklet/mcp/platform/tools.py:100-110, CLAUDE.md:65-75
Architecture and Core Components
The integration utilizes a client-server architecture where the PlatformClient manages communication with the Stacklet GraphQL endpoint. It relies on the fastmcp framework for tool registration and graphql-core for schema introspection and query validation.
PlatformClient
The PlatformClient class handles authentication, session management, and schema operations. It uses httpx.AsyncClient for asynchronous communication and identifies itself via a specific X-Stacklet-MCP header.
Authentication and Headers
The client authenticates using a Bearer token retrieved from StackletCredentials. Every request includes specific headers to ensure proper identification and content handling.
| Header | Value / Purpose |
|---|---|
Authorization | Bearer {access_token} |
Content-Type | application/json |
User-Agent | Defined in package USER_AGENT |
X-Stacklet-MCP | 1 (Identifies MCP traffic) |
Sources: stacklet/mcp/platform/graphql.py:57-62
GraphQL Query Execution Flow
The system processes queries through several safety and validation layers before transmitting them to the Platform API.
- Parsing: The client parses the query string into a
DocumentNode. - Mutation Check: If mutations are disabled via configuration (
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS), the client blocks any document containing a mutation operation. - Schema Validation: The client validates the query against the cached GraphQL schema to catch invalid fields or types locally.
- Execution: The client sends the POST request to the endpoint.
- Response Handling: The client parses the JSON response, handling cases where the backend might return 4xx/5xx status codes along with valid GraphQL data.
Schema Introspection and Discovery
To assist LLMs in constructing valid queries, the integration provides tools for schema exploration. The PlatformClient fetches the full introspection schema and caches it in the server_state to avoid redundant network overhead.
Type Discovery Tools
- list_types: Searches available types using optional regex filters (e.g.,
Account.*). - get_types: Retrieves the full Schema Definition Language (SDL) for specific types, showing fields, arguments, and documentation.
Sources: stacklet/mcp/platform/tools.py:120-135, stacklet/mcp/platform/graphql.py:145-176
Dataset Export System
For large datasets that exceed standard pagination limits, the system provides an asynchronous export mechanism. This bypasses typical connection timeouts by generating CSV files server-side.
Export Process
The export workflow involves initiating a job and then polling for its status.
Export Models
The ExportRequest model defines the structure of the data to be extracted, including JMESPath transformations for JSON fields.
| Field | Description |
|---|---|
connection_field | The GraphQL connection name (e.g., resources, accounts). |
columns | List of ExportColumn objects containing name, path, and optional subpath. |
node_id | Optional ID to start the export from a specific node (e.g., a specific Policy). |
params | Optional filters, typically using FilterElementInput. |
Sources: stacklet/mcp/platform/models.py:108-135, stacklet/mcp/platform/dataset_info.md:28-50
Configuration and Safety
The integration behavior is controlled by environment variables that define safety boundaries for the LLM.
- Mutation Safety: Controlled by
STACKLET_MCP_PLATFORM_ALLOW_MUTATIONS. Iffalse, the tool is marked asread_only=Trueand the client prevents mutation execution. - Timeout Management: The
wait_for_exportmethod implements an exponential backoff strategy (starting at 2 seconds) when polling for asynchronous job completion.
Sources: stacklet/mcp/platform/tools.py:61-68, stacklet/mcp/platform/graphql.py:214-222, README.md:65-72
Summary
The Platform GraphQL Client Integration provides a robust, schema-aware interface for Stacklet governance operations. By combining local validation, instance-level caching, and specialized asynchronous export tools, it enables efficient management of cloud estates. The integration prioritizes safety by allowing administrators to restrict mutation capabilities while providing comprehensive introspection tools for query construction.
Sources: CLAUDE.md:65-75, stacklet/mcp/platform/graphql_info.md:5-15