Agent integration

Agents can use Loom's receipts and manifests to locate a failed job, script entry, or system section, then read the relevant event stream. These pointers reduce the output an agent needs to inspect. They do not determine the cause of a failure, and artifact size depends on the workflow and its output.

This guide sets up the full agent integration stack: CLI, MCP server, Cursor skill, and a starter prompt for creating and validating a workflow.

What you'll set up

Install the CLI and MCP server

Follow the canonical release-install procedure. It pins both an immutable release version and the reviewed installer revision for that release. Do not fetch the installer from main, omit the version, or pass latest.

This installs both loom (CLI) and loom-mcp (MCP server) to ~/.local/bin. Verify the installation:

loom version
loom-mcp --help

The generated executable command reference is the canonical source for supported loom-mcp command-line options.

info

If ~/.local/bin is not on your PATH, follow the guidance printed by the installer.

Load the Loom Workflows skill

The Loom Workflows skill teaches your Cursor agent how to use Loom as the control plane for repo automation. It covers:

• When to use Loom MCP tools vs the CLI
• How to create, validate, compile, and run workflows
• How to triage failures using structured artifacts
• Discovery order for existing repo entrypoints

The skill lives at .cursor/skills/loom-workflows/SKILL.md in any repo that includes it.

To use it, copy the skill directory into your project's .cursor/skills/ folder, or reference the Loom repo's skill directory if you're working within the Loom monorepo.

tip

The skill is automatically activated when your agent detects Loom-related requests like "create a workflow", "run loom", or "debug this pipeline".

Configure the MCP server

Add the following to your project's .cursor/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "loom-mcp": {
      "command": "loom-mcp",
      "transport": "stdio"
    }
  }
}

Restart Cursor or reload the MCP server list to pick up the new server.

One-click setup with Cursor deeplink

Open this link to launch Cursor with a pre-filled prompt that creates a Loom workflow for your repo:

Open in Cursor

Clicking the deeplink opens Cursor with a prompt that instructs your agent to discover repo entrypoints and create a Loom workflow around them. You review and confirm before anything executes.

Verify your setup

Call loom_version from the MCP client. Expected response:

{ "version": "loom v0.0.0-alpha.1" }

If the MCP server is not reachable, confirm that loom-mcp is on your PATH and .cursor/mcp.json is valid JSON.

Prompt your agent

Paste this starter prompt into Cursor:

Create a .loom/workflow.yml for this repo. Use the Loom skill and MCP tools.
Start by discovering the repo's build entrypoints (package.json scripts,
Makefile targets, etc.), then create a thin Loom workflow that wraps them.
Validate with loom check and compile with loom compile.

The prompt asks the agent to find existing automation, create a workflow, validate it, and compile the Graph IR. Review the generated workflow and validation results before running it.

tip

Your agent will use the Loom MCP tools (loom_validate, loom_compile, loom_run_local) and fall back to the CLI when MCP is unavailable.

What your agent gets

MCP tools

Tool	Purpose
loom_version	Verify toolchain
loom_validate	Validate workflow schema
loom_compile	Compile to Graph IR
loom_run_local	Execute locally
loom_read_receipt	Read run/validation receipt
loom_read_logs	Read runtime logs by selector

Docs resources

URI	What you get
loom://docs/index	Compact discovery index
loom://docs/<page>	Full page text
loom://docs/<page>#<section>	Section-level text

For the full specification, see the MCP tools reference and MCP overview.

Next steps

Goal	Link
Run your first workflow	Hello Loom
Understand the artifact model	What is Loom
Browse the CLI	CLI overview
MCP tools reference	MCP tools
Diagnose a failing run	Diagnostics ladder