MCP Server

Stairwell runs a hosted MCP server, so an AI assistant that speaks the Model Context Protocol can query your Stairwell data directly. You point the assistant at https://mcp.api.stairwell.com/mcp, give it your auth token, and then ask questions in plain language: which assets are running which forwarder version, what matched a rule last week, what a hostname has resolved to. The server is read-only, and it sees exactly what your token sees and nothing more.

This is the option to reach for when the question is exploratory. A client you write is better when the question is fixed and the answer feeds something else. See REST APIs for that.

What can I ask it?

Anything answerable from the read side of the Stairwell API. The server exposes one tool per area, so an assistant can chain several of them to answer a question you asked once.

Questions that work well are the ones that would otherwise be four calls and a join:

• "List my active environments, and how many assets in each are running Windows versus macOS."
• "What did rule susp_loader_v3 match in the last week, and which assets were they on?"
• "Has updates.example.net ever resolved to an address in a cloud provider's range?"

The server also carries the query language specification and Stairwell's own field ontology as resources the assistant can read, so it can write a correct filter rather than guessing at field names. That is why a question phrased in your words often produces a query you would have had to look up.

How do I connect a client?

Three details, the same for every client:

Generate the token in the Stairwell app under Settings, then Auth tokens under the Organization section. Quick Start: API Access has the procedure. Then export it, so the token is in your environment rather than in a config file you might commit:

export STAIRWELL_TOKEN="paste-it-here"

Most clients accept a JSON configuration in this shape:

{
  "mcpServers": {
    "stairwell": {
      "type": "http",
      "url": "https://mcp.api.stairwell.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STAIRWELL_TOKEN"
      }
    }
  }
}

Several command line assistants can add it for you instead. Stairwell tests against Claude, Gemini, and Codex:

claude mcp add --transport http stairwell \
  https://mcp.api.stairwell.com/mcp \
  --header "Authorization: Bearer $STAIRWELL_TOKEN"

gemini mcp add --transport http stairwell \
  https://mcp.api.stairwell.com/mcp \
  --header "Authorization: Bearer $STAIRWELL_TOKEN"

codex mcp add stairwell \
  --url https://mcp.api.stairwell.com/mcp \
  --bearer-token-env-var STAIRWELL_TOKEN

These tools change their flags between releases, so check your version's own help output if one is rejected. The three settings in the table above are what any MCP client needs; how it wants them expressed is its business.

How do I know it connected?

Ask the assistant to list your environments. It is the cheapest call on the server, it needs no arguments, and it fails distinctively.

A table of environments means the token, the network, and the tool registration are all working. An authentication error means the token did not reach the server: check the header, and check that you exported the variable in the shell the assistant is actually running in. A reply saying it has no Stairwell tools means the registration did not take, which is a client-side problem rather than a Stairwell one.

The server also ships a prompt named stairwell that loads the orientation the assistant needs about how Stairwell structures its data. In a client that surfaces prompts, load it before your first question; the answers are noticeably better for it, because the assistant stops inferring what an asset or an environment is.

What can it not do?

Four limits, and the first two are the ones people assume away.

• It is read-only, by design. Every tool is a query. Nothing on this server creates, changes, or deletes anything in Stairwell: no uploads, no rule edits, no opinions, no tags. If you want an assistant to change something, it has to go through the API or swell deliberately, which is the point.
• It sees what your token sees. Environment access, roles, and authorization all apply unchanged. An assistant connected with your token cannot read an environment you cannot read, and an answer that comes back empty for you and full for a colleague is two different access levels rather than a bug.
• Not every API endpoint has a tool. The coverage above is the read surface the server exposes today, which is a subset of the full API. For anything outside it, use REST APIs.
• The assistant can be confidently wrong. It is composing queries and summarizing results, and both steps can go astray in ways that read fluently. Treat an answer as a lead: for anything you are going to act on, ask it which tool calls it made and check the underlying data in the app.

What should I know about running it safely?

Two habits, both cheap.

Start the assistant in an empty directory. A command line assistant reads files near where it was started. A directory made for the purpose keeps your Stairwell session from wandering into unrelated local files, and it makes the transcript easier to hand to someone else.

Use a token generated for this. Name it after the use, keep it out of shell history and config files you commit, and revoke it when you stop using it. A token that exists only for your assistant is one you can revoke without breaking an integration, and that is the difference between a five-second fix and an outage.

What should I read next?

• REST APIs, for the surfaces behind these tools and when to write a client instead.
• CEL Query Language, for the filter language the assistant is writing on your behalf.
• Network Intelligence, for what the hostname and IP data is and what it is good for.
• swell, for the same data from a script rather than a conversation.