awslabs.stepfunctions-tool-mcp-server 0.1.14

An AWS Labs Model Context Protocol (MCP) server for AWS Step Functions

AWS Step Functions Tool MCP Server

A Model Context Protocol (MCP) server for AWS Step Functions to select and run state machines as MCP tools without code changes.

Features

This MCP server acts as a bridge between MCP clients and AWS Step Functions state machines, allowing generative AI models to access and run state machines as tools. This enables seamless integration with existing Step Function workflows without requiring any modifications to their definitions. Through this bridge, AI models can execute and manage complex, multi-step business processes that coordinate operations across multiple AWS services.

The server supports both Standard and Express workflows, adapting to different execution needs. Standard workflows excel at long-running processes where status tracking is essential, while Express workflows handle high-volume, short-duration tasks with synchronous execution. This flexibility ensures optimal handling of various workflow patterns and requirements.

To ensure data quality and provide clear documentation, the server integrates with EventBridge Schema Registry for input validation. It combines schema information with state machine definitions to generate comprehensive tool documentation, helping AI models understand both the purpose and technical requirements of each workflow.

From a security perspective, the server implements IAM-based authentication and authorization, creating a clear separation of duties. While models can invoke state machines through the MCP server, they don't have direct access to other AWS services. Instead, the state machines themselves handle AWS service interactions using their own IAM roles, maintaining robust security boundaries while enabling powerful workflow capabilities.

graph LR
    A[Model] <--> B[MCP Client]
    B <--> C["MCP2StepFunctions<br>(MCP Server)"]
    C <--> D[State Machine]
    D <--> E[Other AWS Services]
    D <--> F[Internet]
    D <--> G[VPC]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#bfb,stroke:#333,stroke-width:4px
    style D fill:#fbb,stroke:#333,stroke-width:2px
    style E fill:#fbf,stroke:#333,stroke-width:2px
    style F fill:#dff,stroke:#333,stroke-width:2px
    style G fill:#ffd,stroke:#333,stroke-width:2px

Prerequisites

1. Install uv from Astral or the GitHub README
2. Install Python using uv python install 3.10

Installation

Cursor	VS Code

Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit ~/.aws/amazonq/mcp.json):

{
  "mcpServers": {
    "awslabs.stepfunctions-tool-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.stepfunctions-tool-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "STATE_MACHINE_PREFIX": "your-state-machine-prefix",
        "STATE_MACHINE_LIST": "your-first-state-machine, your-second-state-machine",
        "STATE_MACHINE_TAG_KEY": "your-tag-key",
        "STATE_MACHINE_TAG_VALUE": "your-tag-value",
        "STATE_MACHINE_INPUT_SCHEMA_ARN_TAG_KEY": "your-state-machine-tag-for-input-schema"
      }
    }
  }
}

Windows Installation

For Windows users, the MCP server configuration format is slightly different:

{
  "mcpServers": {
    "awslabs.stepfunctions-tool-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.stepfunctions-tool-mcp-server@latest",
        "awslabs.stepfunctions-tool-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

or docker after a successful docker build -t awslabs/stepfunctions-tool-mcp-server .:

# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

  {
    "mcpServers": {
      "awslabs.stepfunctions-tool-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "--interactive",
          "--env",
          "AWS_REGION=us-east-1",
          "--env",
          "STATE_MACHINE_PREFIX=your-state-machine-prefix",
          "--env",
          "STATE_MACHINE_LIST=your-first-state-machine,your-second-state-machine",
          "--env",
          "STATE_MACHINE_TAG_KEY=your-tag-key",
          "--env",
          "STATE_MACHINE_TAG_VALUE=your-tag-value",
          "--env",
          "STATE_MACHINE_INPUT_SCHEMA_ARN_TAG_KEY=your-state-machine-tag-for-input-schema",
          "--env-file",
          "/full/path/to/file/above/.env",
          "awslabs/stepfunctions-tool-mcp-server:latest"
        ],
        "env": {},
        "disabled": false,
        "autoApprove": []
      }
    }
  }

NOTE: Your credentials will need to be kept refreshed from your host

The AWS_PROFILE and the AWS_REGION are optional, their default values are default and us-east-1.

You can specify STATE_MACHINE_PREFIX, STATE_MACHINE_LIST, or both. If both are empty, all state machines pass the name check. After the name check, if both STATE_MACHINE_TAG_KEY and STATE_MACHINE_TAG_VALUE are set, state machines are further filtered by tag (with key=value). If only one of STATE_MACHINE_TAG_KEY and STATE_MACHINE_TAG_VALUE, then no state machine is selected and a warning is displayed.

Tool Documentation

The MCP server builds comprehensive tool documentation by combining multiple sources of information to help AI models understand and use state machines effectively.

1. State Machine Description: The state machine's description field provides the base tool description. For example:

   Retrieve customer status on the CRM system based on { 'customerId' } or { 'customerEmail' }
   

2. Workflow Description: The Comment field from the state machine definition adds workflow context. For example:

   {
     "Comment": "This workflow first looks up a customer ID from email, then retrieves their info",
     "StartAt": "GetCustomerId",
     "States": { ... }
   }
   

3. Input Schema: The server integrates with EventBridge Schema Registry to provide formal JSON Schema documentation for state machine inputs. To enable schema support:

   • Create your schema in EventBridge Schema Registry
   • Tag your state machine with the schema ARN:

     Key: STATE_MACHINE_INPUT_SCHEMA_ARN_TAG_KEY (configurable)
     Value: arn:aws:schemas:region:account:schema/registry-name/schema-name
     

   • Configure the MCP server:

     {
       "env": {
         "STATE_MACHINE_INPUT_SCHEMA_ARN_TAG_KEY": "your-schema-arn-tag-key"
       }
     }
     

The server combines these sources into a unified documentation format:

[State Machine Description]

Workflow Description: [Comment from state machine definition]

Input Schema:
[JSON Schema from EventBridge Schema Registry]

This comprehensive documentation helps AI models understand both the purpose and technical requirements of each state machine, with formal schema support ensuring correct input formatting.

Best practices

• Use the STATE_MACHINE_LIST to specify the state machines that are available as MCP tools.
• Use the STATE_MACHINE_PREFIX to specify the prefix of the state machines that are available as MCP tools.
• Use the STATE_MACHINE_TAG_KEY and STATE_MACHINE_TAG_VALUE to specify the tag key and value of the state machines that are available as MCP tools.
• AWS Step Functions Description property: the description of the state machine is used as MCP tool description, so it should be very detailed to help the model understand when and how to use the state machine
• Add workflow documentation using the Comment field in state machine definitions:
  • Describe the workflow's purpose and steps
  • Explain any important logic or conditions
  • Document expected inputs and outputs
• Use EventBridge Schema Registry to provide formal input definition:
  • Create JSON Schema definitions for your state machine inputs
  • Tag state machines with their schema ARNs
  • Configure STATE_MACHINE_INPUT_SCHEMA_ARN_TAG_KEY in the MCP server

Security Considerations

When using this MCP server, you should consider:

• Only state machines that are in the provided list or with a name starting with the prefix are imported as MCP tools.
• The MCP server needs permissions to invoke the state machines.
• Each state machine has its own permissions to optionally access other AWS resources.