MCP overview

Loom MCP is a Model Context Protocol server that exposes Loom operations as structured tools and Loom documentation as embedded resources. Validate schemas, compile workflows, run pipelines, and pull the exact reference material you need from Cursor or any MCP-compatible client.

Install the released binaries

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.

The default installer adds both loom and loom-mcp to ~/.local/bin. For MCP setup, the binary you configure in Cursor is loom-mcp.

Executable command reference

The command and options below are generated from the built loom-mcp --help output.

Usage: loom-mcp [options]

Run the Loom MCP server over stdio.

Options:
  -h, --help  Show this help and exit.

Why use it

One integration, full surface — validate, compile, run, and triage through tool calls instead of switching to a terminal.
Structured JSON output — every tool returns typed fields (status, exit code, receipt, log events) that agents and scripts can act on directly.
Server-owned workspace authority — the server authorizes its canonical startup directory. Tool requests cannot expand that authority.
Token-efficient documentation — start with the compact loom://docs/index discovery resource, then fetch a full page or a specific anchored section such as loom://docs/reference/mcp/tools#loom_run_local only when you need it.

Requirements

loom-mcp binary available on the PATH used by your MCP client, or configured with its full path.
Cursor (or any MCP client supporting stdio transport).

Setup

Add the following to .cursor/mcp.json in your repo root (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.

Contributor note: when developing in a Loom checkout, you can use its nix develop environment and point Cursor at ./bin/loom-mcp. Nix is not required to start the released binary.

Verify your setup

Call loom_version from your MCP client. A successful response:

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

If the call fails, confirm that:

Cursor's workspace root matches the repo root.
loom-mcp is on your PATH in the same environment Cursor uses.
The server starts from the repository it should access; see the workspace root contract.

One-click setup with Cursor deeplink

Cursor deeplinks let you share pre-filled MCP configurations and prompts via a single URL. Click the link below to open Cursor with a prompt that instructs your agent to create a Loom workflow using the Loom skill and MCP tools:

cursor://anysphere.cursor-deeplink/prompt?text=Create%20a%20.loom%2Fworkflow.yml%20for%20this%20repo%20using%20the%20Loom%20skill%20and%20MCP%20tools.%20Start%20by%20discovering%20the%20repo%27s%20build%20entrypoints%2C%20then%20create%20a%20thin%20Loom%20workflow%20that%20wraps%20them.

Clicking this opens Cursor with a pre-filled prompt that walks your agent through discovering the repo's build entrypoints and wrapping them in a .loom/workflow.yml. You review and confirm before anything executes.

Loom Workflows skill

The Loom Workflows skill (.cursor/skills/loom-workflows/SKILL.md) teaches Cursor agents how to use Loom as the control plane for repo automation. When the skill is active, your agent will:

Prefer MCP tools over raw shell commands
Follow the discovery order: existing Loom files → MCP → repo entrypoints → CI definitions
Use structured artifacts for failure triage instead of log scraping

See the Agent integration guide for the full setup walkthrough.

Workspace root contract

Loom MCP authorizes only the server process's canonical startup working directory. Start one server process from each repository that it should access.

Tool calls may omit workspace_root or set it to that exact canonical directory for compatibility. Relative aliases, symlink aliases, and other paths fail with WF_TRUSTED_PATH /workspace_root. Use separate server processes to isolate callers.

All workflow, receipt, log, and event inputs are repo-relative. Loom resolves them through the canonical startup root before opening content. Absolute paths, parent traversal, escaping symlinks, and dangling symlinks fail with WF_TRUSTED_PATH at the offending tool field.

Tools

The server registers 6 tools for version lookup, validation, compile, local runs, receipt reads, and runtime-log reads. Each returns typed JSON.

Tool	Purpose
`loom_version`	Print CLI version
`loom_validate`	Validate workflow schema
`loom_compile`	Compile workflow to Graph IR
`loom_run_local`	Execute workflow locally
`loom_read_receipt`	Read a run/validation receipt
`loom_read_logs`	Read runtime logs by selector

See MCP tools reference for parameters, outputs, and the failure triage flow.

Resources

The server exposes Loom documentation as MCP resources under the loom://docs/ URI scheme.

URI pattern	What you get
`loom://docs/index`	Compact JSON discovery index with page-level metadata and excerpts
`loom://docs/<page-path>`	Full embedded page text, for example `loom://docs/intro` or `loom://docs/reference/mcp/tools`
`loom://docs/<page-path>#<section-anchor>`	Section-sized embedded text for targeted retrieval, for example `loom://docs/reference/mcp/tools#loom_run_local`

These resources come from a build-time docs bundle embedded into the loom-mcp binary, not from live source-file reads at runtime. Use loom://docs/index to discover relevant pages cheaply, then fetch the page or anchored section you actually need. Chunk IDs remain an internal bundle detail and are not part of the advertised client interface. The discovery index is application/json; page and section resources are text/plain.

MCP overview

Install the released binaries​

Executable command reference​

Why use it​

Requirements​

Setup​

Verify your setup​

One-click setup with Cursor deeplink​

Loom Workflows skill​

Workspace root contract​

Tools​

Resources​

What to read next​