StepSecurity MCP Server

This page covers the StepSecurity MCP server, which lets AI assistants call the StepSecurity API on your behalf. For the organization-wide inventory of MCP servers configured on developer machines, see MCP Servers under Dev Machine Guard.

The StepSecurity MCP server is a remote Model Context Protocol server that exposes a curated set of StepSecurity APIs as LLM-callable tools. Connect it to Claude Code, Claude Desktop, Cursor, or any other MCP client, and investigate supply chain and CI/CD security issues in plain English: check whether your tenant is exposed to a package compromise, browse recent Harden-Runner detections, trace an IOC across workflow runs, review your Actions security posture, or audit which workflows use a specific GitHub Action.

Authentication uses OAuth with your existing StepSecurity login, so the configuration contains no secrets and is safe to commit to a shared repository. Each user signs in individually, and every tool call is limited to what that user's role can already access.

The server URL is:

https://agent.api.stepsecurity.io/v1/mcp

Quick Start Guide

Step 1: Add the server to your MCP client

Add this to your project's .mcp.json (or your client's MCP settings). No API key is required:

{
  "mcpServers": {
    "stepsecurity": {
      "url": "https://agent.api.stepsecurity.io/v1/mcp"
    }
  }
}

Or with the Claude Code CLI:

claude mcp add --transport http stepsecurity "https://agent.api.stepsecurity.io/v1/mcp"

Step 2: Sign in from the browser

On first use, your MCP client opens a browser window to the StepSecurity console. Sign in the way you always do: SSO, GitHub, or email. Each user authenticates individually, so there are no shared credentials to distribute or rotate.

Step 3: Review and approve access

The consent screen shows the requesting client, your tenant, and the requested scopes. By default the grant is read-only across the resources you can access; you can narrow the selection or expand a section to grant write access (for example, suppression rule writes). Issued tokens are per-user, honor your existing role permissions, and refresh automatically.

Step 4: Ask a question

You do not need to know tool names. The LLM chains tool calls automatically from a natural language prompt. Try:

• "Check if we are affected by the keyv npm supply chain incident."
• "What are the recent detections in StepSecurity for my tenant?"
• "Which workflows use aquasecurity/trivy-action?"
• "Summarize my Actions security posture."

API Key and CI Authentication

Automation that cannot open a browser authenticates with a bearer token in the Authorization header instead of OAuth. Both options below use the same server URL. Because raw API keys do not carry a tenant, pin the tenant with a ?customer= query parameter.

Option 1: API key or personal access token

Use an API key from the StepSecurity API (Tenant Access) integration or a personal access token. Reference it through an environment variable so the key never lands in git; MCP clients expand ${VAR} from each developer's environment:

{
  "mcpServers": {
    "stepsecurity": {
      "url": "https://agent.api.stepsecurity.io/v1/mcp?customer=your-tenant-name",
      "headers": {
        "Authorization": "Bearer ${STEP_SECURITY_API_KEY}"
      }
    }
  }
}

A Tenant Read-Only API Key covers every read tool and is the recommended default.

Option 2: GitHub Actions OIDC (no stored secret)

Workflows exchange their GitHub OIDC token for a short-lived StepSecurity token, so nothing is stored in secrets. Configure an OIDC trust policy on the StepSecurity API (Tenant Access) page first, then mint the token in the workflow and pass it as the Authorization header:

permissions:
  id-token: write

steps:
  - name: Mint StepSecurity API token
    id: ss
    uses: actions/github-script@v7
    with:
      script: |
        const token = await core.getIDToken('your-tenant-name.api.stepsecurity.io')
        const res = await fetch('https://agent.api.stepsecurity.io/v1/your-tenant-name/oidc/token', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ github_oidc_token: token })
        })
        if (!res.ok) {
          core.setFailed(`Exchange failed: ${res.status}`)
          return
        }
        const data = await res.json()
        core.setSecret(data.token)
        core.setOutput('token', data.token)

  # Pass the minted token to the MCP server as the Authorization
  # header, e.g. via the header-auth .mcp.json above with
  # STEP_SECURITY_API_KEY=${{ steps.ss.outputs.token }}

Incident Exposure Checks

The check_incident_exposure tool answers "am I affected by this incident?" in a single call:

1. Pass the incident id (from list_threat_incidents) or the incident group id shown in the dashboard's incident search preset, for example keyv-npm-supply-chain-2026-aug.
2. The tool resolves the full compromised package list for the incident and bulk searches both surfaces at once: CI (workflow runs, PRs, and default branches across your organization) and enrolled dev machines.
3. By default it matches only the exact compromised versions, the same as the dashboard's "exact" preset. Pass anyVersion: true to match any version of the listed packages.
4. It also reminds the assistant to check the incident's C2 indicators with check_ioc_in_baseline, so a prompt like "check if we are affected by the keyv npm supply chain incident" covers packages and IOCs end to end.

If you connected before a new tool was released, disconnect and reconnect the StepSecurity MCP connector (or restart your MCP client session) to pick it up.

Available Tools

Run describe_capabilities from your MCP client for a self-describing summary. Tools by area:

Area	Tools
Connection and tenant	ping, describe_capabilities, get_my_tenant, list_tenant_github_orgs
Detections	list_anomalous_network_calls, list_blocked_domain_calls, list_https_outbound_calls, list_suspicious_process_events, list_secrets_in_build_log, list_imposter_commit_detections, list_suspicious_files, list_detections, analyze_anomalous_calls_by_process
Threat center and exposure checks	list_threat_incidents, get_threat_incident, check_incident_exposure, check_npm_package_exposure, check_pypi_package_exposure, check_npm_package_on_dev_machines, check_python_package_on_dev_machines, check_ioc_in_baseline, find_endpoint_calls_in_tenant, find_repos_using_endpoint
Actions posture and reports	get_actions_security_summary, get_actions_controls_summary, get_control_detail, get_actions_governance_metrics, get_harden_runner_coverage
Workflows and inventory	list_recent_workflow_runs, list_github_api_calls_in_run, list_workflow_actions, search_action_usage, list_reusable_workflows, list_arc_clusters, list_actions_secrets, list_github_apps, list_github_checks, list_artifact_attestations
Policies	list_actions_policies, get_actions_policy, list_harden_runner_rules, list_run_policies, get_run_policy, list_run_policy_evaluations, list_policy_driven_prs, get_policy_driven_pr_config
Suppression rules	list_suppression_rules, get_suppression_rule, preview_suppression_rule
Secure Registry	get_secure_registry_setup, list_secure_registry_controls, list_secure_registry_audit_logs, list_package_config_audits
Dev Machine Guard	list_dev_machines, get_dev_machine, list_dev_machine_inventory, get_dev_machine_inventory_item, list_dev_machine_policies, list_dev_machine_profiles, list_ai_coding_agents, list_ai_agent_sessions

Security Notes

• Read-only by default. The OAuth consent screen grants read-only access unless you explicitly expand a section to include writes. Suppression rule writes require the explicit write scope; with the default grant, write tools are not available.
• Tokens follow your role. Every call is limited to what your StepSecurity role can already access. The MCP server does not grant any permission you do not already have in the console.
• No shared credentials. OAuth tokens are per-user and refresh automatically. For headless use, prefer a Tenant Read-Only API Key referenced through an environment variable, or the GitHub Actions OIDC exchange, which stores no secret at all.

If your MCP client only supports local stdio servers, connect it to the server URL above through mcp-remote, a generic stdio-to-remote bridge that supports both OAuth and header authentication.