> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/administration/admin-console/integrations/stepsecurity-mcp-server.md). # 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](/developer-machines/mcp-servers.md) under Dev Machine Guard. The StepSecurity MCP server is a remote [Model Context Protocol](https://modelcontextprotocol.io/) 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: ```json { "mcpServers": { "stepsecurity": { "url": "https://agent.api.stepsecurity.io/v1/mcp" } } } ``` Or with the Claude Code CLI: ```bash 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)](/administration/admin-console/integrations/stepsecurity-api-tenant-access.md) integration or a [personal access token](/administration/user-settings/personal-access-token.md). Reference it through an environment variable so the key never lands in git; MCP clients expand `${VAR}` from each developer's environment: ```json { "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)](/administration/admin-console/integrations/stepsecurity-api-tenant-access.md) page first, then mint the token in the workflow and pass it as the `Authorization` header: ```yaml 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. {% hint style="info" %} 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. {% endhint %} ### 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. {% hint style="info" %} If your MCP client only supports local stdio servers, connect it to the server URL above through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a generic stdio-to-remote bridge that supports both OAuth and header authentication. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.stepsecurity.io/administration/admin-console/integrations/stepsecurity-mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.