MCP integration

Connect an agent host to LMP over local stdio or a remote Streamable HTTP endpoint. The server is the native Rust binary; the optional @lending-mind/mcp package is only a Node.js compatibility launcher for hosts that need one. The transport follows the Model Context Protocol specification, and its request envelope follows JSON-RPC 2.0.

Quick setup

Choose one transport per host. Use stdio for a local project because it keeps the workspace boundary in the child process configuration. Use Streamable HTTP only when a separately managed service is required. LMP does not use the deprecated SSE transport.

1. Build the server

From the LMP repository:

cargo build --release -p lmp-mcp

The binary is written to target/release/lmp-mcp. For a workspace that is already initialized, use the path to its installed runtime instead:

printf '%s\\n' "$PWD/target/release/lmp-mcp"

The command must point to an executable Rust lmp-mcp binary. Set LMP_WORKSPACE_ROOT to the project the agent is allowed to inspect.

2. Add the project-scoped host entry

Create or update the host configuration in the project root. Keep existing servers in the file and add the lending-mind entry:

{
  "mcpServers": {
    "lending-mind": {
      "command": "/absolute/path/to/lmp/target/release/lmp-mcp",
      "args": [],
      "env": {
        "LMP_WORKSPACE_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Use the file that belongs to the host:

npx create-lmp can generate this entry after it has installed a verified runtime. It writes project files only, preserves other servers, and reports a conflict instead of replacing an existing lending-mind entry. The result is recorded in .lmp_telemetry/host-integrations.json. Claude Desktop is the exception: it owns its application-level settings, so the wrapper never edits that global file. Copy the generated lending-mind entry into Claude Desktop's MCP settings and keep the project path explicit.

3. Verify the connection

Start the configured host, or run the server directly with a JSON-RPC smoke request:

printf '%s\\n' \\
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \\
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \\
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \\
  | LMP_WORKSPACE_ROOT="$PWD" ./target/release/lmp-mcp

The first response should identify lending-mind-mcp. The tools/list response should include lmp_list_minds, lmp_get_instructions, enforce_architectural_axioms, and lmp_evaluate_workspace. If the process cannot start, check the binary path and workspace root before changing host settings.

4. Make the first evaluation

The host should select and verify a Mind, obtain its compiled instructions, and evaluate the changed scope before accepting an agent edit. The direct CLI equivalent is:

cargo run --bin lmp -- evaluate \\
  --mind .lending-mind/mind \\
  --workspace . \\
  --mode enforced \\
  --changed-only \\
  --json

The result is an evidence artifact, not a boolean hint. Keep its Mind digest, workspace revision, selected files, findings, and final state together. Normal evaluation states are pass, needs_revision, and blocked; an evaluation_error means the server could not produce a trustworthy result and must never be treated as a pass.

What the host calls

The server exposes these operations through MCP tools:

Hosts should discover the list at runtime and tolerate unknown tools or fields. Guidance is an input to generation; the evaluation artifact is the decision.

Request sequence

discover capabilities
    ↓
list or select a Mind
    ↓
verify package integrity
    ↓
request compiled guidance
    ↓
let the agent work
    ↓
enforce or evaluate the changed scope
    ↓
show findings and retain the artifact

The host retains the selected profile identifier, package digest, workspace revision, changed-file list, and evaluator result together. A later guidance response must not replace the evidence for an earlier decision.

JSON-RPC transport

In stdio mode, lmp-mcp reads one JSON-RPC message per line and writes one response per line. Paths are constrained to LMP_WORKSPACE_ROOT, and the tool surface does not execute commands or make outbound network requests. For a remote client, use the POST /mcp Streamable HTTP endpoint described below.

Example tool call:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "lmp_evaluate_workspace",
    "arguments": {
      "mind": ".lending-mind/mind",
      "workspace": ".",
      "mode": "enforced",
      "changedOnly": true
    }
  }
}

Remote Streamable HTTP

Start the same binary as an HTTP MCP server when a host cannot launch a local process:

LMP_WORKSPACE_ROOT="$PWD" \
LMP_MCP_TRANSPORT=streamable-http \
LMP_MCP_BEARER_TOKEN="replace-with-a-secret" \
LMP_MCP_ALLOWED_ORIGINS="https://your-agent.example" \
./target/release/lmp-mcp --bind 0.0.0.0 --port 8787

The endpoint is POST /mcp with Content-Type: application/json. The server accepts JSON-RPC request and notification messages and returns JSON responses; notifications receive 202 Accepted. It rejects requests with an unexpected Origin, and any non-local bind requires both LMP_MCP_BEARER_TOKEN and LMP_MCP_ALLOWED_ORIGINS. Put TLS and a normal reverse proxy in front of a public deployment; do not expose the built-in listener directly to the public internet.

The minimum smoke test is:

curl --fail-with-body -sS http://127.0.0.1:8787/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer replace-with-a-secret' \
  -H 'Origin: https://your-agent.example' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

Remote mode is still subject to the same workspace confinement as stdio: LMP_WORKSPACE_ROOT is mandatory in the deployment contract, and every path argument must resolve below that root. The HTTP listener never executes shell commands or grants network access to a tool. Use one isolated service instance per workspace or tenant; do not share a writable workspace root between users.

Pinata IPFS publishing

For local verification without a pinning provider, install the official Kubo CLI from the IPFS Kubo installation guide. The repository records Kubo v0.43.0 adding and retrieving a signed Mind package by CID. A local CID is not a public pin and must not be copied into release metadata as proof of public availability.

IPFS publishing is a release operation, not a browser operation. Configure these repository or environment secrets in the release runner:

PINATA_JWT                 the scoped Pinata upload token
PINATA_GROUP_ID            the group ID from the Pinata group URL
PINATA_GATEWAY_DOMAIN      optional; defaults to gateway.pinata.cloud

The release workflow runs pnpm publish:ipfs:pinata. It uploads every file in each signed production Mind package, verifies each returned CID through the configured Pinata gateway, records the manifest CID and file URLs in the registry, and then reruns the registry verification gate. The JWT is never written to the repository, frontend bundle, registry, or generated docs.

For a controlled local release rehearsal, provide the same variables only in the invoking shell:

PINATA_JWT="..." \
PINATA_GROUP_ID="your-group-id" \
PINATA_GATEWAY_DOMAIN="gateway.pinata.cloud" \
pnpm publish:ipfs:pinata tj-ponytail

The free plan can use Pinata's shared gateway.pinata.cloud gateway; no custom domain upgrade is required. A custom gateway may be configured later if delivery volume requires it.

The command refuses to run without the JWT and group ID, requires HTTPS, rejects symlinks, and does not write registry metadata until upload and retrieval verification have succeeded. Pinata availability, account ownership, and long-term billing are external operational responsibilities.

Request IDs must be unique while requests are in flight. The compatibility adapter rejects a duplicate ID with JSON-RPC -32600; it does not replace the pending request. A malformed request is -32600, an unavailable or invalid operation is reported as a tool error, and a transport/process failure is an execution failure.

Result handling

pass                 → continue to review or merge
needs_revision       → show findings and revise the change
blocked              → stop and repair the integrity or execution boundary
evaluation_error     → preserve the error, repair the evaluator, and rerun

Do not turn a failed result into a pass by retrying unchanged input. A retry is meaningful only after the change or deliberately selected scope has changed.

Malformed JSON-RPC requests, unknown tools, invalid arguments, and process failures are transport or tool errors. They are not policy result states. An evaluation_error is the fail-closed result when evaluation begins but cannot produce a trustworthy artifact.

lmp_get_context returns the selected Mind identity, compiled-instruction digest, a privacy-preserving workspace path hash, and capabilities. It does not return source code or enable commands. lmp_explain_rule explains matching rules without changing the active package. lmp_get_loop_status reads an existing artifact; it does not recompute or mutate it.

Node.js compatibility launcher

Use the Rust server directly when the host accepts a native executable. If a host requires a Node.js command, install @lending-mind/mcp and point it at the Rust binary:

npm install @lending-mind/mcp
LMP_MCP_BIN="/absolute/path/to/lmp-mcp" npx lending-mind-mcp

This launcher preserves line-delimited JSON-RPC, notifications, and request correlation. It does not replace Rust MCP semantics.

Failure checks

• No server appears: confirm the host entry is project-scoped and its command is an absolute executable path.
• Workspace path rejected: set LMP_WORKSPACE_ROOT to the project root; every mind, workspace, and artifact path must remain inside it.
• Server not initialized: send initialize first, then notifications/initialized, before calling a tool.
• Existing configuration changed: restore the conflicting entry and rerun onboarding; LMP reports conflicts rather than overwriting them.
• Evaluation cannot pass: inspect findings and the persisted artifact; changing guidance text does not change a policy result.

Before enabling automatic acceptance, test an invalid signature, malformed request, missing path, failed evaluation, and corrected evaluation. Keep the result artifacts with the source revision and Mind digest.