Skip to content

Connecting to the Spacelift MCP server»

This page covers adding the Spacelift MCP server to your AI client, authenticating, and narrowing the tools it advertises. For what the server is and the tools it exposes, see the overview.

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»

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: adds the mutate tool and the whole intent tool (both can change Spacelift and your cloud), 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.

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):

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

1
export SPACELIFT_API_TOKEN=$(spacectl profile export-token)

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

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

1
export SPACELIFT_API_TOKEN=$(spacectl profile export-token)

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "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:

1
export SPACELIFT_API_TOKEN=$(spacectl profile export-token)

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

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

1
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. If every name you pass is unrecognized (for example, a typo), the parameter has no effect and you get the full set your scope allows, exactly as if you'd omitted it.
  • discover is always included and can't be removed. If your selection is otherwise valid but your scope strips out everything else, you're left with just discover.
  • Omitting the parameter changes nothing. You get every tool your authentication and deployment allow.

Next steps»