Multi-Profile Configuration

The Step MCP Server supports a YAML-based configuration file that lets you define multiple profiles — each targeting a different Step instance or project. This is the recommended approach when you work with more than one Step instance, or manage many projects on the same instance.

For the simple single-instance setup using environment variables, see Getting Started.

Key concepts: profiles and projects

• A profile is a connection identity: a Step instance URL, an API token, and an optional default project. Profiles are reusable across many projects, so you don’t need one profile per project.
• A project is chosen per request. Project-scoped tools accept an optional project argument; when omitted, the server falls back to the profile’s default project.

This separation keeps the common case simple (“run it on my default”) while letting an agent target a specific instance and project per call (“run the smoke test on Payments using customer-prod”).

Configuration file

Location

The server reads up to two files and merges them:

The workspace root is resolved in this order: the CLAUDE_PROJECT_DIR variable (which Claude Code injects into the server), then the server’s working directory. There is no cross-client standard for this. With other clients (VS Code, Cursor, …), either set the server’s working directory to your workspace root (most clients expose a cwd option, often via ${workspaceFolder}), or point STEP_MCP_CONFIG at an absolute path. The user-level file (~/.step-mcp/config.yaml) is always found regardless of the working directory. A committed workspace file lets a team share profiles; your personal user file layers your own on top.

Format

default_profile: acme-dev

profiles:
  acme-dev:
    base_url: https://acme-dev.stepcloud.ch
    token_env: STEP_TOKEN_ACME_DEV     # name of an env var holding the token (preferred)
    default_project: Webshop

  customer-prod:
    base_url: https://step.customer.com
    token_env: STEP_TOKEN_CUSTOMER_PROD
    default_project: Main

Tip: because a workspace file is typically committed to version control, always use token_env there, never token. Set the referenced variables (STEP_TOKEN_*) in your client configuration.

Merging user and workspace files

When both files exist, their profiles are combined:

• The set of profiles is the union of both files.
• When both files define the same key (a profile name or default_profile), the workspace file wins (the server logs which definition it used).

Profile and project resolution

On every tool call the server resolves a profile and, for project-scoped tools, a project.

Profile, in order:

1. the profile argument on the tool call;
2. the STEP_PROFILE environment variable;
3. default_profile from the configuration.

If none resolves, the call fails with an error listing the available profiles.

Project, in order:

1. the project argument on the tool call;
2. the resolved profile’s default project (or STEP_PROJECT).

For read-only tools the project may be omitted. For state-changing tools (such as step_execute_automation_package) on Step Enterprise, the call fails with a clear error rather than guessing if no project can be resolved.

Use step_list_profiles and step_list_projects to discover valid names without opening the configuration file.

Editions: open-source vs Enterprise

The server detects the instance edition automatically and adjusts the project rules accordingly:

• Enterprise — projects exist and are enforced. State-changing tools require a project to resolve to exactly one value.
• Open-source — projects don’t apply. A supplied project is ignored, state-changing tools run without one, and step_list_projects reports that listing is not supported.

Precedence and conflicts

1. If a configuration file is present (user or workspace), it is authoritative. If credential environment variables (STEP_BASE_URL / STEP_API_KEY) are also set, the server refuses to start — choose one mechanism.
2. Otherwise, STEP_BASE_URL defines the single implicit env profile.
3. Otherwise, the server has no usable configuration and reports a clear error.

STEP_PROFILE and STEP_PROJECT are selection inputs, not credentials, so they may be set alongside a configuration file.

Environment variable reference