Skip to content

Spacelift MCP»

The Spacelift MCP server is a remote Model Context Protocol server hosted at the /mcp path of your account. It lets an AI client such as Claude Code, Cursor, VS Code, Codex, or Gemini work with Spacelift in plain language: discovering the GraphQL API, reading and writing Spacelift resources, and managing cloud infrastructure with Intent.

It's how you reach Spacelift Intelligence from outside the UI. Inside the UI, Infra Assistant uses the same set of tools.

Migrating from /intent/mcp

The old /intent/mcp endpoint has been folded into the single /mcp endpoint described here, which also exposes the full Spacelift GraphQL API. /intent/mcp stays available until August 1, 2026, after which it will be removed. Point your MCP client at https://<account-name>.app.spacelift.io/mcp before then.

Capabilities»

The server exposes its capabilities as a set of tools. Which ones a session gets depends on the OAuth scope you grant when you authenticate (see Connecting):

Tool What it does mcp:read mcp:read + mcp:write
discover Browse the API schema: list queries and mutations, inspect types and fields. Always available. ✅ ✅
query Run read-only GraphQL queries and get back the fields you ask for. ✅ ✅
provider Inspect Terraform/OpenTofu provider, resource, and data-source schemas from the OpenTofu registry. Read-only. ✅ ✅
mutate Run GraphQL mutations to change Spacelift resources such as stacks, policies, and runs. ❌ ✅
intent Create, update, delete, refresh, import, resume, read, and check the status of Intent-managed cloud resources. This is what powers the Intent flow. ❌ ✅

A read-only session (mcp:read only) can introspect the API and read your Spacelift and cloud state, but it can't change anything. Asking for intent automatically turns on provider too, since lifecycle operations rely on provider schemas. You can narrow the set of tools further with the tools query parameter.

Two ways to use it»

The same endpoint serves two fairly different goals:

  • Build against the Spacelift API. Let your assistant discover the GraphQL API and write working client code for you, whether that's a dashboard, CI/CD automation, a Slack bot, or a CLI tool. The discover, query, and mutate tools are all you need. See Building against the Spacelift API.
  • Provision infrastructure with Intent. Use the provider and intent tools to create and manage cloud resources in plain language, under Spacelift's policies, state, and audit trail. See Intent.

Authentication»

There are two ways to authenticate:

  • Browser-based OAuth is the default and the best fit for interactive use. You approve access once, and the assistant holds a short-lived token and refreshes it for you. The mcp:read and mcp:write scopes narrow what it can do.
  • A spacectl-issued bearer token is handy for headless, remote, or CI environments. You pass the token in the Authorization header.

Either way, your Spacelift session permissions decide what the assistant can do, scoped by RBAC and login policies. For per-client setup and the full authentication reference, see Connecting.

Building against the Spacelift API»

You don't have to learn the Spacelift GraphQL API yourself. The discover tool introspects it for your assistant, which can then generate working code.

What your assistant can discover»

  • Every available query and mutation, the field definitions and types, and which parameters are required.
  • Operations across stacks, modules, runs, policies, spaces, worker pools, contexts, and blueprints.

Example applications»

  • Dashboards: stack monitoring, deployment history, resource visualization.
  • Automation: CI/CD integrations, scheduled deployments, compliance checking.
  • CLI tools and integrations: batch operations, Slack bots, ticketing and monitoring hooks.

Next steps»

  • Connecting: add the server to your client, authenticate, and pick which tools to expose.
  • Intent: provision and manage infrastructure in plain language.
  • Spacelift API: the underlying GraphQL API and spacectl.