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. Choose an immutable release version and its matching reviewed installer revision. 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 describe loom-mcp --help. Update them when the server's command-line behavior changes.

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, validation receipts, states and 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 loom://docs/index discovery resource, then fetch a full page or a listed 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.

Workflow paths are repo-relative. Recorded reads select a run by its directory name, without path separators. Loom opens content beneath the canonical startup root and rejects escaping symlinks and nonregular files. Rejected selectors use WF_TRUSTED_PATH at the offending tool field.

Tools

The server registers 12 tools for version lookup, validation, compile, local runs, recorded-run discovery, state/event reads, and declared artifact listing/reading. Each returns typed JSON.

Tool	Purpose
`loom_version`	Print CLI version
`loom_validate`	Validate workflow schema
`loom_compile`	Compile workflow to Graph IR
`loom_start_run`	Start server-owned local run
`loom_run_status`	Observe owned or recorded outcome
`loom_cancel_run`	Cancel this server’s owned run
`loom_run_local`	Execute workflow locally
`loom_list_runs`	Discover recorded workflow runs
`loom_read_run`	Read recorded workflow state
`loom_read_events`	Read recorded event messages
`loom_list_artifacts`	List declared archive members
`loom_read_artifact`	Read original member bytes

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`	JSON discovery index with page metadata, excerpts, and ordered section titles and URIs
`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. Each index item retains its page URI and metadata and includes a sections array of { "title", "uri" } entries in page order. Select the title you need, such as loom_read_events, and read its exact advertised URI. Titles can contain underscores or punctuation, and repeated headings have distinct URIs; do not infer an anchor from the title. Chunks without an anchor are not listed as sections. Pages without anchored sections have an empty array.

Full page reads remain available. 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​