MCP Server

Overview

The StackGuardian MCP server connects AI tools directly to the StackGuardian platform. This gives AI agents, assistants, and chatbots the ability to query workflows, retrieve stack information, investigate failures, and analyze your infrastructure state through natural language.

Built for platform engineers and developers who want AI-powered visibility into their StackGuardian operations.

Performance tip

The StackGuardian MCP server works well with all AI models. However, premium models deliver exceptional results with minimal prompting. Free and entry-level models perform reliably for standard queries and may need slightly more detailed instructions for complex tasks.

What you can do

The MCP server gives your AI assistant access to the following:

Area	Capabilities
Workflows	Query status, check configuration, inspect drift, find approval blockers, audit policy coverage, trace template dependencies, create workflows from templates, and update existing workflows
Workflow runs	Fetch execution history, retrieve logs and outputs, list artifacts, and investigate failures
Stacks	Read stack configuration, check deployment status, and retrieve IaC outputs
Templates	Inspect template revisions, find workflows by template, and identify version gaps
Connectors	List connector groups and individual connectors across the organization
Policies	Read policy definitions and check which workflows have policies attached
Organization	Inspect cloud posture and misconfigurations, list roles and private runner groups, and manage vault secrets

For the full list of tools, what each one does and the safeguards on the ones that make changes, see the MCP tools reference.

Prerequisites

Before you begin:

1. A StackGuardian account with access to the organization you want to connect
2. Your region: Europe (app.stackguardian.io) or United States (us.stackguardian.io)
3. A compatible MCP host application, such as Claude Code, Codex, Cursor, VS Code or Gemini CLI

Installation

Quick install

The StackGuardian installer adds the MCP server to your AI tools and installs the StackGuardian skills in one step. It downloads a standalone executable from dl.stackguardian.io, checks it against the release's SHA256SUMS, installs it and runs it. No Node.js is needed.

macOS and Linux

curl -fsSL https://dl.stackguardian.io/add-sg-mcp/install.sh | sh

Windows (PowerShell)

irm https://dl.stackguardian.io/add-sg-mcp/install.ps1 | iex

If you have Node.js 18 or later, you can run npx @stackguardian/mcp-wizard instead.

Then:

1. Pick your region. The StackGuardian dashboard opens in your browser. Sign in if needed, then choose the organization, the roles the agent may use and how long the access lasts.
2. Back in the terminal, choose the agents to connect. The ones found on your machine are preselected.
3. Restart those agents.

The installer writes a grant token bound to the organization and roles you approved, not your full API key. You can revoke it at any time from Profile > Connected apps in the dashboard.

To check the installation, run add-sg-mcp status (npx @stackguardian/mcp-wizard status if you used npx), or in Claude Code run /mcp and look for StackGuardian-<YOUR_ORG>.

note

The standalone executables are available for macOS (Apple Silicon and Intel), Linux with glibc (x64 and arm64) and Windows x64. On Alpine and other musl-based systems, use npx @stackguardian/mcp-wizard.

Installer options

Pass options to the first run after sh -s --:

curl -fsSL https://dl.stackguardian.io/add-sg-mcp/install.sh | sh -s -- --region eu -a claude-code

On a server or in CI, skip the browser with an API key:

curl -fsSL https://dl.stackguardian.io/add-sg-mcp/install.sh | sh -s -- --token <YOUR_TOKEN> --org <YOUR_ORG> --region eu -y --all

Set these environment variables on the sh side of the pipe, for example curl … | ADD_SG_MCP_NO_RUN=1 sh:

Variable	Effect
ADD_SG_MCP_VERSION	Release to install. Defaults to the latest
ADD_SG_MCP_INSTALL_DIR	Install directory. Defaults to ~/.local/bin, or %LOCALAPPDATA%\add-sg-mcp\bin on Windows
ADD_SG_MCP_NO_RUN	1 installs the executable without running it

Run add-sg-mcp --help for the full list of commands, including login, remove and logout.

note

The installer doesn't set up Claude Desktop or Claude on the web. Add StackGuardian there as a custom connector instead, as described below.

Additional client setup

To configure a client by hand, use these values. Claude Desktop and Claude on the web only need the MCP server URL:

• <YOUR_ORG>: your StackGuardian organization name
• <YOUR_TOKEN>: your StackGuardian API key
• MCP server URL:
  • EU region: https://api.app.stackguardian.io/api/v1/orgs/<YOUR_ORG>/mcp/
  • US region: https://api.us.stackguardian.io/api/v1/orgs/<YOUR_ORG>/mcp/

note

The API key inherits permissions from your user role. Ensure you have the necessary access rights for the operations you want to perform.

Claude Code

After installing Claude Code, run this command in your terminal:

  claude mcp add --transport http StackGuardian \
      "https://api.app.stackguardian.io/api/v1/orgs/<YOUR_ORG>/mcp/" \
      -H "Authorization: apikey <YOUR_TOKEN>"

Claude Desktop and Claude on the web

Claude Desktop and claude.ai connect to StackGuardian as a custom connector and sign you in with OAuth. You don't need an API key.

1. Go to Settings > Connectors, then click Add > Custom connector
2. Configure:
   • Name: StackGuardian
   • URL: the MCP server URL for your region
     • EU region: https://api.app.stackguardian.io/api/v1/orgs/<YOUR_ORG>/mcp/
     • US region: https://api.us.stackguardian.io/api/v1/orgs/<YOUR_ORG>/mcp/
3. Click Continue
4. Click Connect next to the StackGuardian connector. The StackGuardian sign-in opens in your browser. Sign in if needed and approve the access

A connector you add on claude.ai is also available in Claude Desktop, and the other way around, when you're signed in to the same Claude account.

note

On Team and Enterprise plans, an owner may need to add the connector for the organization before members can connect to it.

Add a custom connector in Claude

VS Code Copilot

Prerequisites

• VS Code 1.99 or later
• GitHub Copilot extension (any plan, including free)
• Your StackGuardian API token
• Your StackGuardian organization name

Installation

Step 1: Configure the MCP server

Create .vscode/mcp.json in your project root, or run MCP: Open User Configuration from the Command Palette for a global config:

  {
    "servers": {
      "stackguardian": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://api.app.stackguardian.io/api/v1/orgs/<YOUR_ORG>/mcp/",
          "--header",
          "Authorization: apikey <YOUR_TOKEN>"
        ]
      }
    }
  }

Step 2: Start the MCP server

A Start button appears at the top of the mcp.json file after saving. Click it to start the server and discover available tools.

Start the MCP server

Step 3: Access via Copilot Chat

1. Open Copilot Chat (Ctrl+Alt+I on Windows/Linux or Cmd+Ctrl+I on macOS)
2. Switch to Agent mode from the mode dropdown
3. Click the tools icon (🛠) to verify StackGuardian tools are listed

note

MCP tools are only available in Agent mode. They will not appear in Ask or Edit mode.

Use cases

The MCP server is most powerful when you give your assistant specific context. Include workflow group names, stack names, or resource identifiers in your prompts for faster and more accurate results.

Workflow governance

Create a workflow from a template

"Create a workflow called payment-service in the production workflow group using the empty-tf-resource template in StackGuardian."

Spins up a new workflow in an existing workflow group without leaving your AI assistant. Creating the workflow stores its configuration without starting a run.

Update an existing workflow

"Update the payment-service workflow in the production workflow group to use revision 3 of the empty-tf-resource template in StackGuardian."

Applies configuration changes to an existing workflow directly through your AI assistant, without navigating the platform manually.

Find workflows with no policy attached

"Which workflows in the production workflow group don't have any policy attached in StackGuardian?"

Surfaces workflows that were deployed without governance coverage, a common blind spot in fast-moving teams.

Find workflows blocked on approval

"Which workflows in the staging workflow group have been waiting for approval for more than 48 hours in StackGuardian? Who are the approvers?"

Identifies stuck deployments and the people who need to action them, so you can unblock your team without manually checking the platform.

Find workflows with drift detected

"How many workflows in the infrastructure workflow group currently have drift detected in StackGuardian?"

Gives you an instant count of drifted workflows so you can prioritize remediation before the gap between desired and actual state grows.

Template management

Find workflows using a specific template revision

"Which workflows in my organization are still using template empty-tf-resource revision 2 in StackGuardian?"

Essential before deprecating or updating a template revision. Shows the full scope of what will be affected.

Workflow run investigation

Investigate a failed workflow run

"Why did workflow run #1247 in the production workflow group fail in StackGuardian? Help me figure out what happened."

Retrieves logs and execution details for a specific run so you can diagnose failures without switching between tabs.

Check workflow health

"How healthy are the workflows in the mcp-testing workflow group in StackGuardian?"

Returns a summary of workflow statuses across a group, a quick way to assess the overall health of a set of deployments.

Retrieve run facts for a workflow

"Show me the run facts for the latest run of the payment-service workflow in the production workflow group in StackGuardian."

Returns detailed execution data for a specific workflow run, including resource changes, outputs, and deployment details.

note

Run facts are available for individual workflows only. Querying run facts across multiple workflows at once will consume significant context window and may produce incomplete results.

Organization-wide visibility

Get a full stack status overview

"What's the current status of all stacks in the engineering workflow group?"

Aggregates stack health across a workflow group in one query instead of checking each stack individually.

Security and permissions

The MCP server respects the permissions associated with your credential: the roles you approved for a grant token, or your user roles for an API key. If your credential doesn't have access to certain resources, those operations will fail with a permission error. For read-only use cases, viewer-level access is sufficient.

Skills

Skills are guided flows that ship alongside the StackGuardian MCP server. Once installed, your agent loads the relevant one automatically when you ask for a matching task. There's nothing to invoke by name.

Safer changes. Infrastructure APIs carry semantics that a parameter list can't show: some fields merge with what's already stored, others replace it outright, and some settings only mean something in combination with another. A skill tells the agent which is which, so an ordinary request like "add a tag" doesn't quietly drop the existing ones and report success.

Review before write. Choices are fetched live and presented to you rather than recalled from memory: groups, connectors, templates and their default values. The agent summarizes the intended change in plain language and waits for your confirmation, and previews template upgrades with a dry run before anything is applied.

The right operation for the intent. Creating a resource, editing its settings, and moving it to a new template revision are separate flows with different risks. Skills route the request to the correct one instead of overloading a single call.

Consistent results. The same sequence runs every time and for everyone, so outcomes don't depend on who is asking or how often they've done it before.

Fewer failed attempts. Names, options and defaults are resolved up front, so fewer calls are spent discovering that a value was wrong.

note

Skills guide the agent; they don't grant access. Every call is still made with your own credentials and enforced by the platform's permissions, and write operations are available only where your environment enables them.

The quick install installs the skills along with the MCP server, and each run refreshes them. To install only the skills, run this command in your terminal:

npx skills add StackGuardian/stackguardian-mcp

Follow the interactive prompts to select which skills and agents to install to. Skills are installed globally and available automatically in your AI assistant once the process completes.

You can also browse the available skills directly in the skills folder of the stackguardian-mcp repository.