spacelift

Spacelift

Procedural guide for the spacelift MCP. Two surfaces share one MCP - the Spacelift control plane (GraphQL: stacks, runs, policies, spaces, integrations) and Intent (lifecycle of actual cloud resources via OpenTofu providers). Most tasks touch both.

Tool map

Tool	Purpose
discover	Browse the GraphQL schema. Modes: queries, mutations, type. Always run before query/mutate.
query	Execute a read-only GraphQL operation. select uses GraphQL selection-set syntax.
mutate	Execute a GraphQL mutation. Modifies state - requires explicit confirmation (see below).
provider	Inspect OpenTofu providers + resource schemas. Modes: search, describe, resources-describe, datasources-describe. Mandatory before intent create/update/import.
intent	Manage real infrastructure: create, update, delete, refresh, import, read, resume, status. Supports async=true.

Decision tree

User wants to...	Start with
Read/list/inspect Spacelift entities (stacks, runs, policies, ...)	discover → query
Modify a Spacelift entity (create/update/delete/attach)	discover → mutate (gated, see below)
Create/update real cloud infra (EC2, S3, GCS, ...)	provider → intent (gated, see below)
Import existing cloud infra into intent state	provider search → intent import
Detect drift on managed cloud infra	intent refresh
Trigger / confirm / discard a stack run	mutate with runTrigger / runConfirm / runDiscard

Reference selector

Load only the file that matches the question. Do not preload references.

Question / task	Load
GraphQL syntax, pagination, search predicates, selection sets	references/api-discovery.md
Stack lifecycle, settings, dependencies, drift, scheduling, blueprints	references/stacks.md
Run state machine, plan/confirm/discard/apply, retry, cancel, tasks	references/runs.md
Policy types (10 of them), role bindings, spaces, attachment rules	references/policies-spaces.md
AWS/Azure/GCP integrations, VCS providers, contexts, worker pools	references/integrations.md
Creating an intent project, configElements, attaching policies/AWS/worker pool, exporting to IaC	references/intent-projects.md
intent operation mechanics: provider workflow, async polling, resume gating	references/intent-operations.md
About to mutate or delete? Read this every time	references/mutations-safety.md

End-to-end recipes: examples/01-read-only-audit.md, examples/02-stack-run-lifecycle.md, examples/03-intent-end-to-end.md.

Mandatory ordering rules

1. Always discover before query/mutate. Don't guess operation names or argument shapes.
2. Always provider resources-describe before intent create/update/import. Skipping causes "expected X arguments" errors. Provider schemas drift; do not cache across sessions.
3. Always read references/mutations-safety.md before any mutate or intent delete/update.

Destructive-operation gate

Before any mutate, intent create, intent update, or intent delete:

1. State the operation, target, and concrete diff (current → proposed) in plain prose.
2. For intent delete: enumerate dependents first (use searchIntentResources or provider resources-describe linkage).
3. Block on YES or CONFIRM (case-insensitive). No other token confirms. No carryover from prior turns - each destructive call needs a fresh confirmation.

Read-only operations (query, discover, provider search/describe, intent read/status/refresh) need no confirmation.

Async polling pattern (intent)

Some intent operations take 10-30 minutes. Use async=true, then poll with intent status:

• Backoff: 2s → 4s → 8s → 16s → 32s → cap at 60s.
• Never re-dispatch a slow operation - the worker is already running.
• If status returns PENDING_REVIEW, do not call resume. Wait for READY_FOR_EXECUTION, then resume after explicit human approval.

Pitfalls catalog

Each is real and frequent. Apply the mitigation by default.

Pitfall	Mitigation
User asks "how many X do I have?" - listing every entity is slow and pollutes context	Use searchXxxSuggestions with predicates and select filteredCount - returns the count without entities
Deleted context still attached to stacks - runs fail with missing env var	Before contextDelete, list attachedStacks; either detach or warn
Worker pool deleted while runs queued - orphaned runs	Drain workers (workerDrainSet), wait for queue to clear, then delete
stackDelete(destroyResources: true) runs a destroy plan - destroys real infra	Treat as the most destructive operation; require CONFIRM and enumerate dependents
variables passed as JSON-encoded string ("{\"id\":\"x\"}")	Pass as a JSON object: {"id": "x"}
Calling runConfirm on a run not in UNCONFIRMED	Read state first; only UNCONFIRMED accepts confirm
intent resume on PENDING_REVIEW	Only resume when status is READY_FOR_EXECUTION
Stale provider schema → "expected X arguments"	Run provider resources-describe before each intent create/update
Async over-polling burns tokens / triggers rate limits	Exponential backoff capped at 60s; never re-dispatch
Selection-set bloat (name description createdAt updatedAt ...)	Request only fields you'll use this turn
Pagination forgotten - missing entries on accounts with >50 entities	Use first/after with pageInfo.hasNextPage; loop until exhausted or stop early
Mutations are not idempotent (slug collisions on stackCreate)	query for existence first; handle 409-shaped errors as "already exists"
Deprecated fields silently hidden by discover	Pass includeDeprecated: true only when truly needed
Tracked commit drifts behind remote silently	stackSyncCommit to refresh; do not assume trackedCommit is current
Treating IntentProject as separate from Spacelift entities	It has space, workerPool, attachedPolicies like a stack - use the same auth/policy mental model

Outside this skill

When concepts go beyond what's here (vendor-specific behaviors, billing edge cases, integration-test setups, custom blueprint authoring), consult https://docs.spacelift.io/sitemap.xml to find the relevant page, then WebFetch.