---
title: "Build workflows with an AI assistant over MCP"
description: "Connect Claude, Cursor, VS Code and other AI clients to Workflow Suite's MCP server and let them draft, validate, simulate and monitor workflows."
canonical: "https://docs.workflow-suite.app/build-workflows-with-ai-over-mcp"
---

# Build workflows with an AI assistant over MCP

MCP (Model Context Protocol) is a standard way for AI assistants to use tools. Workflow Suite has an MCP server, so an assistant can look up triggers and actions, draft a workflow, check it, try it against a sample event and read the run history, in a conversation with you.

## Connect an AI client

1. Open **Developer**, tab **API keys**, and select **Create API key**. For building workflows choose **Read & write**. See the levels in [Developer API and MCP](https://docs.workflow-suite.app/developer-api-and-mcp.md).
2. Copy the key. It is shown once, together with ready setup commands for AI clients, with the key already filled in.
3. Or open the tab **MCP**. It shows the **MCP server (Streamable HTTP)** URL and, under **Connect an AI client**, a command or a config snippet for Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI and OpenAI Codex.

The server URL is `https://shopify.workflow-suite.app/api/mcp`. Any client that speaks MCP over Streamable HTTP with a Bearer token can connect:

```text
Authorization: Bearer bwk_your_key_here
```

## The key's level decides the tools

An assistant only sees the tools its key allows. A read-only key cannot even see the tools that change something.

| Level | Tools, for example |
| --- | --- |
| Read only | `list_workflows`, `get_workflow`, `list_triggers`, `list_actions`, `list_workflow_templates`, `list_shopify_mutations`, `list_shopify_queries`, `get_trigger_sample`, `validate_workflow`, `get_permissions`, `get_workflow_requirements`, `list_workflow_runs`, `get_workflow_run`, `get_plan` |
| Read & write | also `create_workflow`, `update_workflow`, `use_workflow_template`, `enable_workflow`, `disable_workflow`, `simulate_workflow`, `test_workflow`, `test_workflow_step`, `restore_workflow_version`, `create_secret`, `kv_set`, `write_file`, `create_smtp_sender` |
| Read, write & execute | also `run_workflow`, `rerun_workflow_run`, `send_test_email` |

The full list with each tool's level is on the **Developer** page.

## How an assistant builds a workflow

The tools are made for this loop, and the server tells the assistant about it:

1. **Look up** the trigger and the steps: `list_triggers`, `get_trigger_sample` for the fields of the event, `list_actions`, and for anything else `list_shopify_mutations` and `get_shopify_mutation`, which returns a ready step.
2. **Validate** the draft with `validate_workflow`. Nothing is stored. It returns problems, missing permissions and the secrets the draft names.
3. **Save** with `create_workflow`. A workflow is always created turned off.
4. **Check what is still needed** with `get_workflow_requirements`: permissions only you can grant, and secrets to create.
5. **Simulate** with `simulate_workflow` and a realistic event. It is a preview by default: reads and conditions run, changes are only reported. The result shows the path taken and every step's result.
6. **Turn on** with `enable_workflow`, then watch `list_workflow_runs` and `get_workflow_run`.

## Prompts that work well

Say what should happen in your store, and what should start it. Let the assistant look the details up.

- "When an order above 500 comes in, tag it high-value and post it to Slack. The webhook URL is in the secret SLACK_WEBHOOK_URL. Validate and simulate before you save."
- "Which of my workflows failed in the last week, and why?"
- "Take the template for archiving completed orders, change it to 30 days and show me a simulation."
- "My workflow Low stock alert never starts. Check its requirements and the last runs."

## What an assistant cannot do

Some things need you, in the app. The tools say so when they come up:

- **Grant a permission.** `get_permissions` returns what is missing and the link to the Permissions page.
- **Read a secret.** An assistant can create a secret with a value you give it, and use secrets by name. No tool returns a value. Better still: create secrets yourself in the app, and only tell the assistant their names.
- **Create API keys, choose a plan, turn on paid extra runs, add alert recipients and phone numbers.**
- **Use the step debugger.** `simulate_workflow` and `test_workflow_step` give the same insight.

> [!WARNING]
> **Treat the assistant like a colleague with a key**
> - **Start with a read & write key, not an execute key.** Building, validating and simulating as a preview needs no execute level. With an execute key an assistant can start real runs, which change your store and count against your plan.
> - **Review before you turn on.** Open the new workflow in the editor. It is an ordinary workflow: you see every step, can test it yourself and have its versions.
> - **Mind personal data.** Run data is returned masked, but the mask is a heuristic and free text can still hold personal data. What an assistant reads is processed by that assistant's provider.
> - **Revoke the key** on the Developer page when you are done.

## Functions too

The same server has tools for saved functions: list, create, update, test unsaved code and read function runs. An assistant can write the JavaScript for a **Run function** step and try it before it goes into a workflow. See [Run code and functions](https://docs.workflow-suite.app/run-code.md).

## Related

- [Developer API and MCP](https://docs.workflow-suite.app/developer-api-and-mcp.md)
- [Test, preview and debug](https://docs.workflow-suite.app/test-preview-and-debug.md)
- [Permissions and store data access](https://docs.workflow-suite.app/permissions-and-store-data-access.md)