Skip to content

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 through three 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).

Your coding assistant uses these tools to discover the API structure, understand authentication, and generate working code in any language.

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.

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

CLI:

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

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

1
2
3
4
5
6
7
8
{
  "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:

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

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

1
2
3
4
5
6
7
{
  "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):

1
2
3
4
5
6
7
8
[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):

1
2
3
4
5
6
7
8
{
  "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):

1
2
3
4
5
6
7
{
  "mcpServers": {
    "spacelift": {
      "url": "https://<account-name>.app.spacelift.io/mcp"
    }
  }
}

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

Authentication»

The Spacelift MCP server uses browser-based OAuth. 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.

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.