MCP Server

Prerequisites

To proceed, ensure the following prerequisites are met:

Stairwell Account: An active Stairwell account with production environment access is required.
Stairwell Authentication Token: A valid authentication token is necessary for server access.
npm Installation: Node Package Manager (npm) must be installed to manage LLM CLI tool dependencies.

1. Set Your Authentication Token

Set your Stairwell authentication token as an environment variable. This token is used by CLI tools for secure communication with the MCP server.

export STAIRWELL_AUTH_TOKEN="YOUR_AUTH_TOKEN"

Replace "YOUR_AUTH_TOKEN" with your generated Stairwell authentication token.

2. Configure the MCP Server Address

Configure your LLM CLI tool to connect to the Stairwell Production MCP server. This involves setting the MCP URL and adding the server to your LLM's configuration.

First, set the Production MCP URL as an environment variable:

export MCP_URL=https://mcp.api.stairwell.com/mcp

Then, use the appropriate command for your chosen LLM:

3. Install and Configure LLM CLI Tools

Install the required LLM CLI tool; we currently test with Claude, Gemini and Codex/GPT. It is recommended to install these in your home directory to prevent dependency conflicts.

For Gemini:

cd $HOME
npm install @google/gemini-cli
~/node_modules/.bin/gemini mcp add stairwell-mcp -t http $MCP_URL http -H "Authorization: Bearer $STAIRWELL_AUTH_TOKEN"

For Claude:

cd $HOME
npm install @anthropic-ai/claude-code
~/node_modules/.bin/claude mcp add stairwell-mcp -t http $MCP_URL http -H "Authorization: Bearer $STAIRWELL_AUTH_TOKEN"

For Codex/GPT:

cd $HOME
npm install @openai/codex
~/node_modules/.bin/codex mcp add stairwell-mcp --url $MCP_URL --bearer-token-env-var STAIRWELL_AUTH_TOKEN

4. Using the MCP Server

After configuring the MCP server, you can interact with it using your LLM's CLI tool. It is recommended to operate from a dedicated, temporary directory (e.g., mcp-test), to minimize the amount of local files the LLM will try to access.

Create and navigate to this directory:

cd $HOME
mkdir mcp-test
cd mcp-test

Launch your LLM using the appropriate command:

# For Gemini
~/node_modules/.bin/gemini

# For Claude
~/node_modules/.bin/claude

# For Codex (GPT)
~/node_modules/.bin/codex

Within the LLM's interactive shell, access Stairwell's MCP tools by typing /stairwell. This will load the default Stairwell LLM prompt. From there, you should be able to ask any question you want and get an answer, for example List me all my active environments, and how many assets are running Windows vs MacOS in each.

Limitations

The current MCP server is, by design, only allowed to query data, not modify it. You should be able to access any data available through the Stairwell public API through MCP, but the API calls that create, modify or delete data in any way are currently not supported.

Please Provide Feedback!

We're interested in your feedback! Let us know your thoughts and share the cool stuff you build with us at [email protected]