MCP server

@leadrails/mcp is the official Model Context Protocol server for LeadRails. Install it, point your AI agent at it, and the agent can manage sources, destinations, routes, and read events — using the same v1 API documented here, signed with your API key.

What it does

The server exposes the LeadRails v1 surface as MCP tools. An agent (Claude Desktop, Claude Code, Cursor, anything that speaks MCP) can call those tools to:

List, create, pause, revoke, and rotate signing secrets for sources.
List, create, pause, and test destinations.
Wire routes between sources and destinations.
Read delivery events and replay individual events on Pro+ plans.

Tools are scoped to whichever workspace your API key belongs to. The server speaks stdio transport in v1 — install locally, run locally. A remote OAuth-backed transport is on the roadmap.

Source code: github.com/leadrails/mcp (MIT-licensed). The package on npm is @leadrails/mcp. File issues + PRs against the GitHub repo; we mirror it from our private monorepo on every release.

Quick try (no install)

The fastest possible try-it-out, no global install:

LEADRAILS_API_KEY=lr_live_yourkeyhere npx @leadrails/mcp

The server starts and waits on stdin for MCP framing. You'd normally wire it into an MCP-capable client (below), but running it bare is a good way to confirm the binary works.

Permanent install

Install globally with pnpm (recommended):

pnpm add -g @leadrails/mcp

Or with npm:

npm install -g @leadrails/mcp

The binary is named leadrails-mcp. Run it directly to confirm the install — without an API key it exits with a clear error pointing you at the key-generation flow:

leadrails-mcp

Environment variables

Variable	Required	Default	Notes
`LEADRAILS_API_KEY`	Yes	—	API key starting with `lr_live_`. Create one at app.leadrails.dev/settings/api-keys.
`LEADRAILS_API_URL`	No	`https://api.leadrails.dev/v1`	Override to point at staging (`https://api-staging.leadrails.dev/v1`) or a custom origin. Include the `/v1` path.

Treat LEADRAILS_API_KEY like any other secret. The MCP config files below sit in your home directory — don't commit them to a public repo.

Claude Desktop

Edit your Claude Desktop config. Path by OS:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add a mcpServers entry:

{
  "mcpServers": {
    "leadrails": {
      "command": "npx",
      "args": ["-y", "@leadrails/mcp"],
      "env": {
        "LEADRAILS_API_KEY": "lr_live_yourkeyhere"
      }
    }
  }
}

Restart Claude Desktop. The LeadRails tools appear under the tools menu the next time you start a conversation.

Claude Code

Claude Code reads MCP servers from ~/.claude.json (or the project-scoped .claude/settings.json). Use the claude mcp add CLI:

claude mcp add leadrails npx -y @leadrails/mcp \
  --env LEADRAILS_API_KEY=lr_live_yourkeyhere

Or edit ~/.claude.json manually:

{
  "mcpServers": {
    "leadrails": {
      "command": "npx",
      "args": ["-y", "@leadrails/mcp"],
      "env": {
        "LEADRAILS_API_KEY": "lr_live_yourkeyhere"
      }
    }
  }
}

Cursor

Cursor reads MCP servers from ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project). Add:

{
  "mcpServers": {
    "leadrails": {
      "command": "npx",
      "args": ["-y", "@leadrails/mcp"],
      "env": {
        "LEADRAILS_API_KEY": "lr_live_yourkeyhere"
      }
    }
  }
}

Restart Cursor. The agent picks up the LeadRails tools on next reload.

Try it out

Once the server is wired in, ask your agent something like:

"List my LeadRails sources."
"Pause the source named Website contact form."
"Show me events from yesterday where any destination delivery failed."
"Create a Slack destination called Lead alerts pointing at this webhook URL: …"
"Wire the source src_01J… to the destination dst_01J…."

The agent will call the corresponding tool, you'll see the request + response, and (depending on your client) be asked to approve the write. The MCP server itself does NOT confirm — your client is in charge of the human-in-the-loop policy.

Troubleshooting

Symptom	Cause	Fix
Tools never appear in the client	Config file path wrong, or client wasn't restarted after edit.	Double-check the path for your platform above; fully quit and reopen the client.
Server starts but every tool call returns `invalid-api-key`	The `LEADRAILS_API_KEY` is missing the `lr_live_` prefix, was revoked, or belongs to a different workspace.	Create a fresh key at Settings → API keys and export it into the config.
`plan-required` on event reads	`/v1/events` is Pro+. Starter keys are blocked.	Upgrade in Billing, or read events in the dashboard.
`rate-limit-exceeded` after a burst of calls	Per-key rate limit (see Errors).	Back off; the `RateLimit-Reset` header tells you how many seconds to wait.
Server logs "command not found: npx"	Node isn't on the PATH the client sees (common on macOS GUI launches).	Either install Node via a system installer that updates `/etc/paths.d`, or use the absolute path (`/opt/homebrew/bin/npx`) in the config.

Reference

The MCP server is a thin wrapper around the v1 REST API. Every tool maps 1:1 to a REST endpoint documented under API Reference. For the canonical list of tools + their JSON-schema arguments, see the @leadrails/mcp README on npm — it stays in lockstep with the published package.