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 or https://<account-name>.app.us.spacelift.io/mcp for US-based accounts. 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.

Remember to replace the URL with https://<account-name>.app.us.spacelift.io/mcp if your account is based in the US.

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.

Remember to replace the URL with https://<account-name>.app.us.spacelift.io/mcp if your account is based in the US.

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.

Remember to replace the URL with https://<account-name>.app.us.spacelift.io/mcp if your account is based in the US.

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.

Remember to replace the URL with https://<account-name>.app.us.spacelift.io/mcp if your account is based in the US.

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.

Remember to replace the URL with https://<account-name>.app.us.spacelift.io/mcp if your account is based in the US.

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

Custom redirect hosts

By default Spacelift only accepts OAuth redirects to loopback addresses (localhost, 127.0.0.1, ::1) and to a built-in list of known client hosts, which covers every client listed above. A client or proxy outside that list is refused when it registers:

invalid redirect URI: https://mcp.example.com/oauth/callback:
unsupported redirect URI to https host "mcp.example.com"

This normally comes up when you put an MCP proxy or gateway in front of Spacelift, so the callback goes to a hostname you own instead of to the client vendor.

Account admins can allow their own hosts: click Organization settings, then navigate to OAuth redirect allowlist. The list is additive, so your entries extend the built-in list rather than replacing it and the standard clients keep working.

Each entry is a bare hostname, or a single leading *. wildcard that covers subdomains but not the domain itself:

Entry	Matches	Doesn't match
mcp.example.com	mcp.example.com	other.example.com
*.example.com	mcp.example.com, a.b.example.com	example.com

Custom hosts must use HTTPS

The allowlist only extends the accepted https hosts. Plain http redirects stay restricted to loopback addresses no matter what the list contains, so a custom host has to be served over HTTPS.

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.

Remember, if your account is based in the US, the URLs in the config files should point to https://<account-name>.app.us.spacelift.io/mcp.

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 # for most accounts

https://<account-name>.app.us.spacelift.io/mcp?tools=query,provider # for US-based accounts

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

• Spacelift MCP overview: what the server is and what each tool does.
• Intent: provision and manage infrastructure through natural language.
• Building against the Spacelift API: generate client code from the GraphQL API.