Spacelift API integration via MCP

You don't need to learn the Spacelift GraphQL API. We've built GraphQL introspection tooling into Spacelift's hosted MCP server that lets your coding assistant discover and use the API automatically.

How it works

Spacelift runs a remote MCP (Model Context Protocol) server at the /mcp path of your account. It exposes the entire Spacelift GraphQL API to AI agents — and, if you grant write access, the Spacelift Intent infrastructure tools as well — through up to five tools:

• discover — browse the API schema: list available queries and mutations, inspect types and their fields.
• query — execute read-only GraphQL queries with the fields you want returned.
• mutate — execute GraphQL mutations to modify Spacelift resources (stacks, policies, runs, and more).
• provider — inspect Terraform/OpenTofu provider schemas, resources, and data sources discovered through the OpenTofu registry. Read-only.
• intent — create, update, delete, refresh, import, resume, read, and check the status of Intent-managed cloud resources. Powers the Intent flow.

Your coding assistant uses these tools to discover the API structure, understand authentication, and generate working code in any language. For pure API automation, the first three tools are all you need; the provider and intent tools become relevant when you want the assistant to manage cloud resources directly.

Info

The same endpoint also powers Spacelift Intent infrastructure lifecycle tools. If you are looking to create cloud resources directly through natural language rather than generate client code, see the Intent documentation.

Setup

Configure your coding assistant

Add the Spacelift MCP server to your coding assistant. The server URL is https://<account-name>.app.spacelift.io/mcp — replace <account-name> with your Spacelift account name.

Claude CodeGeminiCodexVS CodeCursor

You can add the MCP server via command-line interface (CLI) or by editing your config file.

CLI:

claude mcp add spacelift -t http https://<account-name>.app.spacelift.io/mcp

Config file (.mcp.json at repo root):

{
  "mcpServers": {
    "spacelift": {
      "type": "http",
      "url": "https://<account-name>.app.spacelift.io/mcp"
    }
  }
}

You can add the MCP server via command-line interface (CLI) or by editing your config file.

CLI:

gemini mcp add --transport http spacelift https://<account-name>.app.spacelift.io/mcp

Config file (.gemini/settings.json at repo root):

{
  "mcpServers": {
    "spacelift": {
      "httpUrl": "https://<account-name>.app.spacelift.io/mcp"
    }
  }
}

You can add the MCP server by editing your config file.

Config file (~/.codex/config.toml):

[features]
rmcp_client = true

[mcp_servers.spacelift]
url = "https://<account-name>.app.spacelift.io/mcp"
startup_timeout_sec = 20.0
experimental_use_rmcp_client = true
enabled = true

Once configured run codex mcp login spacelift to authenticate.

You can add the MCP server by editing the workspace config file.

Config file (.vscode/mcp.json at repo root):

{
  "servers": {
    "spacelift": {
      "type": "http",
      "url": "https://<account-name>.app.spacelift.io/mcp"
    }
  }
}

Alternatively, open the VS Code Command Palette and run MCP: Add Server to add the server to your user profile for global access.

You can add the MCP server by editing the config file.

Config file (~/.cursor/mcp.json for global, or .cursor/mcp.json at project root):

{
  "mcpServers": {
    "spacelift": {
      "url": "https://<account-name>.app.spacelift.io/mcp"
    }
  }
}

Alternatively, go to Cursor Settings > MCP to add the server.

Authentication

You can authenticate the MCP server in one of two ways: browser-based OAuth (the default, recommended for interactive use) or a spacectl-issued bearer token passed as an HTTP header (handy when a browser flow is impractical, such as headless, remote, or CI-style environments, or when you already have spacectl configured).

Browser-based OAuth

The Spacelift MCP server uses browser-based OAuth by default. The first time your assistant connects, it opens a browser window where you approve access to your Spacelift account. After approval, the assistant holds a short-lived token and refreshes it transparently.

No API keys or spacectl setup is required for the hosted MCP server — your Spacelift session permissions govern what the assistant can do, scoped by RBAC and login policies.

Scopes

The consent page exposes two scopes; both are pre-selected by default:

• mcp:read — grants discover, query, and the read-only provider tool. Pick this alone when you only need an assistant that can introspect the API or read Spacelift state, for example to scaffold a dashboard or a read-only client.
• mcp:write — grants mutate and the destructive operations of the intent tool, and implies mcp:read. Pick this when the assistant needs to change Spacelift resources or manage cloud infrastructure through Intent.

Uncheck mcp:write to limit a session to read-only access. Granted scopes are tied to the session, so to broaden access later you have to re-authenticate.

Authenticating with a spacectl token

Instead of the browser-based OAuth flow, you can authenticate the MCP server with a bearer token issued by the spacectl CLI. The assistant sends this token in the Authorization header on every request, exactly as it would for the GraphQL API.

This is the better fit when an interactive browser flow is awkward — for example on a remote or headless machine — or when spacectl is already part of your workflow.

Prerequisites:

1. Install spacectl and authenticate with spacectl profile login.
2. Run spacectl profile export-token to print the bearer token. Each client below either runs this command for you or expects the exported value.

Token-based auth is not scoped

Unlike OAuth, a spacectl token is not narrowed by the mcp:read/mcp:write consent screen — it grants whatever access the authenticated user (or API key) has under RBAC and login policies. The token is also short-lived: only Claude Code's headersHelper mints a fresh one on each connection. For the other clients you re-export the token and reconnect once it expires.

Claude CodeGeminiCodexVS CodeCursor

Use headersHelper to run spacectl profile export-token on every connection, so the assistant always has a fresh token.

Config file (.mcp.json at repo root):

{
  "mcpServers": {
    "spacelift": {
      "type": "http",
      "url": "https://<account-name>.app.spacelift.io/mcp",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(spacectl profile export-token)\"'\"}'"
    }
  }
}

The command after headersHelper must print a JSON object of header name/value pairs to standard output.

Export the token into an environment variable, then reference it from a static headers map:

export SPACELIFT_API_TOKEN=$(spacectl profile export-token)

Config file (.gemini/settings.json at repo root):

{
  "mcpServers": {
    "spacelift": {
      "httpUrl": "https://<account-name>.app.spacelift.io/mcp",
      "headers": {
        "Authorization": "Bearer ${SPACELIFT_API_TOKEN}"
      }
    }
  }
}

Export the token into an environment variable and point Codex at it with bearer_token_env_var:

export SPACELIFT_API_TOKEN=$(spacectl profile export-token)

Config file (~/.codex/config.toml):

[features]
rmcp_client = true

[mcp_servers.spacelift]
url = "https://<account-name>.app.spacelift.io/mcp"
bearer_token_env_var = "SPACELIFT_API_TOKEN"
startup_timeout_sec = 20.0
experimental_use_rmcp_client = true
enabled = true

Reference the token through an input variable so VS Code prompts for it securely instead of storing it in plain text. Paste the output of spacectl profile export-token when prompted.

Config file (.vscode/mcp.json at repo root):

{
  "servers": {
    "spacelift": {
      "type": "http",
      "url": "https://<account-name>.app.spacelift.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:spacelift-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "spacelift-token",
      "type": "promptString",
      "description": "Spacelift API token (run: spacectl profile export-token)",
      "password": true
    }
  ]
}

Export the token into an environment variable, then reference it from a static headers map:

export SPACELIFT_API_TOKEN=$(spacectl profile export-token)

Config file (~/.cursor/mcp.json for global, or .cursor/mcp.json at project root):

{
  "mcpServers": {
    "spacelift": {
      "url": "https://<account-name>.app.spacelift.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SPACELIFT_API_TOKEN}"
      }
    }
  }
}

Choosing which tools to expose

Alpha feature

The tools parameter is an Alpha feature: it may contain bugs, is subject to change, and you should not depend on it — support is provided on a best-effort basis. Omitting the parameter always preserves the default behavior, so existing configurations are unaffected.

By default the MCP server advertises every tool your authentication and deployment allow. You can narrow that set by appending a tools query parameter — a comma-separated list of the tool names to keep — to the server URL in your client configuration. Two reasons to do this:

• Lower token cost. Each tool's name, description, and input schema is sent to the model on every turn. The provider and intent tools carry large, multi-paragraph descriptions, so hiding the tools you don't need trims the per-request payload.
• Better tool choice. Models pick more reliably when they aren't offered tools irrelevant to the task.

This works for every authentication method. OAuth sessions already get a coarse version of it through the mcp:read/mcp:write scopes, but API-key and spacectl-token callers had no narrowing control until now — for them, the tools parameter is the first.

Accepted names match the tool names exactly: query, mutate, provider, and intent. The discover schema browser is always included and cannot be removed — it's the catalogue the other tools depend on. For example:

• ?tools=query — a read-only API investigator.
• ?tools=query,provider — a lookup-only CI helper.

Append the parameter to the URL wherever you configured it, for example:

https://<account-name>.app.spacelift.io/mcp?tools=query,provider

How the selection resolves:

• It can only narrow, never expand. The selection is intersected with what your authentication scope and deployment already permit, so it can never grant a tool you wouldn't otherwise have — an mcp:read OAuth session that requests mutate still won't receive it. Per-action authorization remains the authority at execution time, regardless of which tools are advertised.
• Selecting intent also enables provider, since Intent operations rely on provider schema lookups.
• Unknown names are ignored, and a selection that resolves to nothing leaves only the discover tool.
• Omitting the parameter changes nothing — you get every tool your authentication and deployment allow.

What your coding assistant can discover

API structure

• All available queries and mutations
• Field definitions and types
• Required vs optional parameters
• Return types and nested structures

Operations

• Stack management (create, update, delete, trigger runs)
• Module registry access
• Resource monitoring
• Run execution and monitoring
• Policy management
• Spaces, worker pools, contexts, and blueprints

Development workflow

Step 1: Tell your assistant what you want to build

• "Build a React dashboard showing stack status"
• "Create a Python script for automated deployments"
• "Make a CLI tool for managing stacks"

Step 2: Assistant explores the API

• Introspects the GraphQL schema via discover
• Finds relevant operations
• Understands data structures

Step 3: Assistant generates working code

• Creates properly typed API clients
• Implements error handling
• Follows best practices

When the assistant needs to authenticate the generated application itself (rather than use the MCP OAuth session), point it to the API authentication guide.

Example applications

Your assistant can build:

• Dashboards: Stack monitoring, deployment history, resource visualization.
• Automation: CI/CD integrations, scheduled deployments, compliance checking.
• Mobile apps: Deployment approvals, status monitoring, notifications.
• CLI tools: Developer productivity, batch operations, administrative tasks.
• Integrations: Slack bots, ticketing systems, monitoring tools.

Language support

The introspection works with any language or framework:

• Web: React, Vue, Angular, Next.js, plain JavaScript.
• Backend: Node.js, Python, Go, Java, C#, Ruby.
• Mobile: React Native, Flutter, native development.
• Desktop: Electron, native applications.
• Infrastructure: Terraform providers, Kubernetes operators.

Getting started

1. Configure the MCP server in your coding assistant.
2. Approve the OAuth flow the first time your assistant connects.
3. Start building. The assistant will handle API discovery and code generation automatically.