Agent integration

Loom is designed to work with AI agents as first-class consumers. Every runtime artifact — receipts, pipeline manifests, event streams — is structured data with deterministic pointers. Agents consume these artifacts directly, without scraping logs or guessing at failure causes, keeping token budgets low and diagnosis accurate.

This guide sets up the full agent integration stack: CLI, MCP server, Cursor skill, and a starter prompt that lets your agent create and run Loom workflows autonomously.

What you'll set up

Install the CLI and MCP server

curl -fsSL https://gitlab.com/beepbeepgo/loom-build/loom/-/raw/main/install-loom.sh | bash

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

loom version
loom-mcp --help

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.

Your agent will discover the repo's existing automation, scaffold a workflow, validate the schema, and compile the Graph IR — all without leaving the editor.

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