MCP Setup Guide

Patchloom includes an MCP (Model Context Protocol) server for structured tool calls. MCP-capable AI agents can call Patchloom tools directly with JSON parameters, with no shell command construction, no quoting issues, and no --apply flag needed.

Official MCP Registry

Patchloom publishes to the official MCP Registry as io.github.patchloom/patchloom. The listing points clients at the crates.io and npm packages and starts the stdio server with mcp-server.

Repo metadata lives in server.json at the repository root. Ownership markers (required by the registry) are:

• crates.io: a visible mcp-name: io.github.patchloom/patchloom line in the crate README (HTML comments are stripped on crates.io, so the token must be plain markdown text).
• npm: mcpName in the published package.json (injected during the release publish-npm job; cargo-dist does not emit it).

On each release, after crates.io and npm publish succeed, the Release workflow calls Publish MCP Registry, which stamps the version into server.json, confirms those markers, authenticates with GitHub OIDC, and runs mcp-publisher publish. You can re-run it manually via workflow_dispatch with an explicit version (for example after a failed publish).

Smithery (local MCPB)

Smithery can list local stdio servers via an MCPB bundle (URL publish is for hosted Streamable HTTP endpoints; Patchloom's primary agent path is local stdio).

The bundle lives under mcpb/ and runs:

1. patchloom mcp-server if the binary is on PATH, else
2. npx -y patchloom@<version> mcp-server (Node.js 18+).

make pack-mcpb   # writes target/mcpb/patchloom-<version>.mcpb (override with VERSION=x.y.z)
# One-time auth + CI secret:
#   smithery auth login
#   export SMITHERY_API_KEY=$(smithery auth whoami --full | sed -n 's/^SMITHERY_API_KEY=//p')
#   gh secret set SMITHERY_API_KEY --repo patchloom/patchloom
bash scripts/publish-smithery.sh   # REST upload (reliable for stdio MCPB)

CI: .github/workflows/publish-smithery.yml packs after each GitHub Release and publishes when the SMITHERY_API_KEY secret is set (soft-skip otherwise).

Glama directory

Glama indexes open-source MCP servers for discovery, quality scores, and optional hosted connectors.

Listing (live): glama.ai/mcp/servers/patchloom/patchloom (search API id pk95432szu). Repo ownership metadata is in root glama.json (maintainers GitHub usernames).

Canonical short description (match server.json / MCP Registry, max 100 chars):

Agent-safe structured edits: JSON/YAML/TOML/md/AST, dry-run, batch/tx. Not a filesystem MCP.

If the Glama profile still shows the older “AI agent file editing via MCP…” blurb, open the listing as a maintainer and set the description to the text above (GitHub sync does not always replace an existing Glama description).

First-time submit (already done for Patchloom)

1. Sign in at glama.ai (GitHub OAuth is supported).
2. Open MCP Servers and click Add MCP Server.
3. Submit GitHub URL https://github.com/patchloom/patchloom with the description above.
4. Confirm search: GET https://glama.ai/api/mcp/v1/servers?query=patchloom returns a non-empty servers list.

There is no public unauthenticated submit API.

Verify MCP support

The MCP server is included by default in all pre-built binaries and in recommended installs (Homebrew, Scoop, npm npx / global, crates.io). winget usually tracks the latest GitHub Release after Microsoft publishes the version PR; Chocolatey often lags while versions wait for moderation. Prefer Scoop or a GitHub Release binary when you need a known-current MCP server. Verify it works:

patchloom mcp-server --help

Configure your agent

Set command to an absolute path to the binary, or to patchloom if the CLI is already on PATH (Homebrew, Scoop, cargo install, installer).

Examples:

JSON configs need escaped backslashes on Windows paths (C:\\\\Users\\\\...\\\\patchloom.exe). Prefer the bare name patchloom when the shim is on PATH.

Grok (config.toml)

Add to ~/.grok/config.toml:

[mcp_servers.patchloom]
command = "patchloom"
args = ["mcp-server"]
env = { PATCHLOOM_MCP_SURFACE = "core" }

Claude Desktop (JSON)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "patchloom": {
      "command": "patchloom",
      "args": ["mcp-server"],
      "env": {
        "PATCHLOOM_MCP_SURFACE": "core"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

Create .vscode/mcp.json in your workspace root:

{
  "servers": {
    "patchloom": {
      "command": "patchloom",
      "args": ["mcp-server"],
      "env": {
        "PATCHLOOM_MCP_SURFACE": "core"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

Create .cursor/mcp.json in your workspace root:

{
  "servers": {
    "patchloom": {
      "command": "patchloom",
      "args": ["mcp-server"],
      "env": {
        "PATCHLOOM_MCP_SURFACE": "core"
      }
    }
  }
}

Or use the Patchloom VS Code extension to configure MCP automatically via the Patchloom: Configure MCP command.

Generic stdio MCP

Any MCP client that supports stdio transport can connect by spawning patchloom mcp-server as a subprocess. The server communicates via JSON-RPC over stdin/stdout.

Available tools

Patchloom exposes two registration paths for MCP tools (see src/cmd/mcp/surface.rs for the inventory and policy):

Prefer the registry for new simple write tools. Do not force custom tools into the registry when that would lose multi-file, batch, or read UX.

Custom tools are inventoried in CUSTOM_MCP_TOOLS_CORE (always registered) and CUSTOM_MCP_TOOLS_AST (only when the ast feature is enabled). Default builds expose 58 tools (registry + custom). Builds without ast omit the AST tools so list_tools stays honest about what is callable.

How MCP mode differs from CLI mode

Multi-step plans and concurrency guidance (important for agents)

For any work involving more than one edit (especially on the same file or related files), prefer the execute_plan tool over issuing many individual tools:

• One execute_plan call = atomic execution of a mixed plan (doc.set + md.replace_section + create + replace + ...).
• MCP execute_plan strips format and validate lifecycle steps from the submitted plan. Those steps do not run (they are CLI tx / project-config only). Use .patchloom.toml if the workspace needs lifecycle shells.
• Top-level MCP strict overrides the plan only when the caller sends it. Omitting it leaves plan.strict unchanged (so {"plan":{"strict":false}} is honored).
• write_policy on the plan is still accepted.

Example inline plan (JSON):

{
  "version": 1,
  "strict": true,
  "operations": [
    { "op": "doc.set", "path": "package.json", "selector": "version", "value": "2.0.0" },
    { "op": "md.replace_section", "path": "AGENTS.md", "heading": "## Commands", "content": "Run make check.\n" },
    { "op": "file.create", "path": "REPORT.md", "content": "# Summary\n" }
  ]
}

Critical rules for agents (to avoid lost updates and races):

• Do not issue concurrent write tools against the same path(s) unless using execute_plan.
• Serialize writes per path. Parallelize only across completely disjoint paths.
• Per-call "ok" does not mean the combined result is coherent if you interleave writers yourself.
• Use one execute_plan for any logical multi-edit task.

These semantics are also documented in the tool instructions returned by the MCP server and in patchloom agent-rules --mode mcp.

Tool surface (full vs core)

By default the server registers the full tool inventory (registry + custom handlers, including AST when built with ast). That default stays for compatibility.

Recommended for coding agents (Grok, Claude, Cursor, dual native tools + MCP): start with the core pack so tool schemas stay small. Upgrade to full when you need AST or advanced standalone tools.

export PATCHLOOM_MCP_SURFACE=core
patchloom mcp-server

server_info includes "surface": "core"|"full", "tool_count", package "version", MCP "protocol_version" (same as the initialize handshake), and when surface is full a "recommendation" string pointing coding agents at core. Invalid PATCHLOOM_MCP_SURFACE values are rejected (do not silently fall back).

Handshake instructions match the active surface: core mode lists only the core tools (it does not advertise full-inventory names such as create_file or ast_*). Instructions also include a short canonical name map (CLI / plan / MCP) and an explore rule (prefer list_files / search_files / read_file over shell cat/find/ls and over a second generic filesystem MCP when Patchloom MCP is connected).

Note: execute_plan remains on core, so multi-op plans can still run create/delete/AST-style plan ops (and plan apply.fragment) when the host sends a full plan. Standalone tools such as apply_fragment, create_file, and ast_* are full-inventory only. The env flag reduces the tool schema surface for small agents; it is not a capability sandbox for the plan catalog.

Short system-prompt rules (not the full ~50KB dump):

patchloom agent-rules --surface core

Coding-agent install recipes (core by default)

Coding agents should use the core pack so tool schemas stay small. Full inventory remains the product default when the env is unset (compatibility). Set PATCHLOOM_MCP_SURFACE=core in the client config for Grok, Claude, Cursor, and Codex-style hosts.

Grok / config.toml

[mcp_servers.patchloom]
command = "patchloom"
args = ["mcp-server"]
env = { PATCHLOOM_MCP_SURFACE = "core" }

Cursor (~/.cursor/mcp.json or project .cursor/mcp.json)

{
  "mcpServers": {
    "patchloom": {
      "command": "patchloom",
      "args": ["mcp-server"],
      "env": {
        "PATCHLOOM_MCP_SURFACE": "core"
      }
    }
  }
}

Claude Desktop / Claude Code style MCP config

{
  "mcpServers": {
    "patchloom": {
      "command": "patchloom",
      "args": ["mcp-server"],
      "env": {
        "PATCHLOOM_MCP_SURFACE": "core"
      }
    }
  }
}

Codex / generic stdio MCP

{
  "name": "patchloom",
  "command": "patchloom",
  "args": ["mcp-server"],
  "env": {
    "PATCHLOOM_MCP_SURFACE": "core"
  }
}

Do not also install a generic filesystem MCP only for list/read when Patchloom MCP is connected: use list_files, search_files, and read_file instead. Use full surface (unset env or full) when you need standalone AST tools or advanced md/doc tools as first-class MCP tools (execute_plan on core can still run plan ops).

Example fragment for copy-paste: mcp-core.example.json.

Design notes: mcp-surface-tiers.md.

Debugging and logging

The MCP server can log every tool call to a JSONL file for debugging and performance analysis. Each line records the tool name, duration, and success/failure status.

Enable logging with the --log flag:

patchloom mcp-server --log /tmp/patchloom-mcp.log

Or set the PATCHLOOM_MCP_LOG environment variable (the --log flag takes precedence):

export PATCHLOOM_MCP_LOG=/tmp/patchloom-mcp.log
patchloom mcp-server

Each line is a JSON object:

{"ts":1749123456789,"tool":"replace_text","duration_ms":3,"ok":true}
{"ts":1749123456800,"tool":"doc_set","duration_ms":5,"ok":false,"error":"file not found"}

Configuring logging in your MCP client

Grok (config.toml) -- pass the env var to the MCP server subprocess:

[mcp_servers.patchloom]
command = "/path/to/patchloom"
args = ["mcp-server"]
env = { PATCHLOOM_MCP_LOG = "/tmp/patchloom-mcp.log" }

Or use --log in the args:

[mcp_servers.patchloom]
command = "/path/to/patchloom"
args = ["mcp-server", "--log", "/tmp/patchloom-mcp.log"]

Claude Desktop / VS Code / Cursor (JSON) -- use --log in the args:

{
  "mcpServers": {
    "patchloom": {
      "command": "/path/to/patchloom",
      "args": ["mcp-server", "--log", "/tmp/patchloom-mcp.log"]
    }
  }
}

Or pass the env var (Claude Desktop supports env in server config):

{
  "mcpServers": {
    "patchloom": {
      "command": "/path/to/patchloom",
      "args": ["mcp-server"],
      "env": { "PATCHLOOM_MCP_LOG": "/tmp/patchloom-mcp.log" }
    }
  }
}

Security model

The MCP server enforces path containment: every path must resolve inside the working directory where patchloom mcp-server was started. Relative paths are preferred. Absolute paths that resolve inside that workspace are allowed (agents often concatenate server_info.cwd with a relative path). ../ traversal, absolute paths outside the workspace, and symlinks that escape the workspace are rejected. This prevents an agent from editing files outside the project.

Each individual tool validates every path before execution.

Streamable HTTP transport

By default, the MCP server uses stdio transport (ideal for local IDE/agent integration). With --http, the server switches to Streamable HTTP transport, allowing remote MCP clients to connect over the network.

Streamable HTTP has no authentication and no token. The default bind is loopback (127.0.0.1). Binding a non-loopback address (0.0.0.0, a LAN IP, or a public IP) is refused unless you pass --allow-unauthenticated.

Basic HTTP

# Default: listen on 127.0.0.1:8080 (loopback)
patchloom mcp-server --http

# Custom port on loopback
patchloom mcp-server --http --port 3000

# Explicit loopback bind
patchloom mcp-server --http --host 127.0.0.1

The MCP endpoint is served at /mcp (e.g., http://127.0.0.1:8080/mcp).

Do not copy-paste --host 0.0.0.0 as a default. All-interfaces HTTP is unauthenticated (there is no token) and requires an explicit opt-in:

# All interfaces: unauthenticated, opt-in required
patchloom mcp-server --http --host 0.0.0.0 --allow-unauthenticated

HTTPS with native TLS

TLS encrypts the connection but still does not authenticate clients. Non-loopback binds still need --allow-unauthenticated. There is no bearer token.

patchloom mcp-server --http --host 0.0.0.0 --port 443 \
  --tls-cert cert.pem --tls-key key.pem --allow-unauthenticated

Both --tls-cert and --tls-key must be provided together. The server uses rustls (no OpenSSL dependency).

HTTP transport flags

Connecting a remote MCP client

Use any MCP client that supports Streamable HTTP transport. Example with the rmcp Rust client:

#![allow(unused)]
fn main() {
// Requires `rmcp` 3.x with client + HTTP transport features (see crates.io).
use rmcp::ServiceExt;
use rmcp::transport::StreamableHttpClientTransport;

let transport = StreamableHttpClientTransport::from_uri("http://localhost:8080/mcp");
let client = ().serve(transport).await?;
// Negotiate initialize; tool calls go through client.peer().call_tool(...).
}

Logging with HTTP transport

The --log flag works identically with HTTP transport:

patchloom mcp-server --http --log /tmp/mcp.log

Graceful shutdown

The HTTP server shuts down gracefully on Ctrl+C (SIGINT): active SSE streams are terminated, in-flight requests complete, and the server exits cleanly.

Example tool call

An MCP-capable agent sends:

{
  "method": "tools/call",
  "params": {
    "name": "doc_set",
    "arguments": {
      "path": "config.yaml",
      "selector": "database.port",
      "value": 5432
    }
  }
}

Patchloom parses the YAML, changes database.port to 5432, preserves all comments and formatting, and writes the file. The agent receives a success response with no further action needed.