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

Install the latest release:

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

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

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.
Predictable workspace resolution — when workspace_root is omitted, the server uses its current working directory. Pass workspace_root explicitly when you need to pin a specific repo root.
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

Nix flake environment — the server expects the Loom workspace environment to be available under nix develop.
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: if you're developing from a Loom repo checkout, you can point Cursor at the repo-local ./bin/loom-mcp binary instead. Keep that as a source-based workflow, not the default user install path.

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 Nix flake environment is available for the workspace.

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

When workspace_root is omitted, Loom MCP uses the server process's current working directory as the workspace root.

Run loom-mcp from the repo root, or pass workspace_root explicitly when the server may start elsewhere.

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​

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​