@lsf-lab/lp-mcp

An MCP server that exposes a lead-engagement, campaign-management, and knowledge-base API to AI agents over stdio. 76 tools across 15 categories. Designed for Claude Desktop, Cursor, Continue, and any other Model Context Protocol client.

What is "lp"?

lp is the namespace prefix for every tool exposed by this server (e.g., lp.create_lead, lp.query_kb, lp.whoami). Short, opaque, and easy to filter when multiple MCP servers are loaded into the same client.

Quickstart (60 seconds)

Add this to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "lp": {
      "command": "npx",
      "args": ["-y", "@lsf-lab/lp-mcp"],
      "env": {
        "LP_API_KEY": "ldk_your_api_key_here",
        "LP_API_URL": "https://api.example.com"
      }
    }
  }
}

Restart your client. The 76 tools should appear in the tool palette. Try lp.whoami first to verify the connection.

Configuration

| Variable | CLI flag | Required | Description | |---|---|---|---| | LP_API_KEY | --api-key | yes | API key for authentication. Should start with ldk_ or leadio_sk_. | | LP_API_URL | --api-url | yes | API base URL (e.g., https://api.example.com). No trailing slash needed. | | LP_BYPASS_TOKEN | --bypass-token | no | Deployment-protection bypass token. Sent as the x-vercel-protection-bypass header on every request. Only needed when targeting deployments behind Vercel SSO or similar platform-level protection. |

CLI flags override environment variables. For production use, prefer environment variables — flags are visible in ps aux and shell history.

Tools

The server exposes 76 tools organized into 15 categories:

| Category | Count | What it does | |---|---|---| | Leads | 12 | Create, list, search, get, archive, unarchive, mark do-not-contact, get enrichment, get timeline, get full context, export | | Sequences | 8 | Create, list, get, update, enroll, pause, resume, list enrollments | | Enrichment | 6 | Trigger enrichment per lead, batch enrich, generate content, get pipeline run, get content run status, retry pipeline step | | Admin | 6 | Whoami, get/update team config, list/revoke/rotate API keys | | Proposals | 6 | Create, list, get, update, send, respond | | Clients | 5 | Create, list, get, update, update health | | Signals | 5 | Reply, engagement, call notes, campaign outcome, log activity | | KB | 4 | Get company KB, query KB, search KB vectors, ingest document | | Campaigns | 4 | Generate social content, list, get, get campaign leads | | Meetings | 4 | Create, list, get, update | | Presentations | 4 | Get, list, get events, get engagement | | Tags | 4 | Set action tag, set state tag, remove tag, get lead tags | | Emails | 3 | List variants, get, regenerate | | Analytics | 3 | Pipeline summary, pipeline stats, list engagement signals | | Graph | 2 | Get entity by ID, list entities for a lead |

For the full list, run lp.whoami after connecting and inspect your client's tool palette, or look at tests/__snapshots__/tool-snapshot.test.ts.snap in the source repo.

Authentication

Generate an API key from the web UI of your installation. The MCP authenticates by sending Authorization: Bearer <LP_API_KEY> on every request. The server-side validates against the mcp_api_keys table and enforces per-key scopes — your key needs the right scope for each tool (e.g., leads:read, kb:ingest, presentations:read).

To audit what scopes your current key has, call lp.whoami.

Deployment Protection (Vercel SSO bypass)

If LP_API_URL points at a deployment behind Vercel "Deployment Protection" (preview branches, password-protected, or SSO-protected), the API edge will reject requests with a 401 HTML page before they reach your auth code. You will see HTTP 401 responses with HTML bodies in the tool errors.

To bypass platform-level protection, set LP_BYPASS_TOKEN to the project's automation bypass secret (Vercel project settings → Deployment Protection → Protection Bypass for Automation). The MCP forwards it as the x-vercel-protection-bypass header on every request.

{
  "mcpServers": {
    "lp": {
      "command": "npx",
      "args": ["-y", "@lsf-lab/lp-mcp"],
      "env": {
        "LP_API_KEY": "ldk_your_api_key_here",
        "LP_API_URL": "https://staging.example.com",
        "LP_BYPASS_TOKEN": "your_bypass_secret_here"
      }
    }
  }
}

When LP_BYPASS_TOKEN is unset, no header is sent — the package works normally against unprotected APIs.

Common errors

| Symptom | Cause | Fix | |---|---|---| | LP_API_KEY is required | Env var or flag not set | Set LP_API_KEY in your MCP client config under env. | | LP_API_URL is required | Env var or flag not set | Set LP_API_URL to the API base URL. | | Tool returns {"status":401,"code":"authentication_error"} | API key is invalid or expired | Regenerate the key from the web UI. Run lp.whoami to verify. | | Tool returns {"status":403,"code":"permission_error"} | Your key does not have the required scope for that tool | Check lp.whoami for your scopes; regenerate with the missing scope from the web UI. | | Tool returns 401 with HTML body containing "Authentication Required" | The deployment is behind Vercel SSO and the bypass token is missing or wrong | Set LP_BYPASS_TOKEN (see "Deployment Protection" above). | | Tool returns {"status":429,"code":"rate_limit"} | You hit the per-key rate limit | Wait. The LpClient retries 429 automatically with exponential backoff; if you see this in a final response, the retries also exhausted. | | npx -y @lsf-lab/lp-mcp hangs on first run | npx is downloading and caching the package | Wait. Subsequent runs are instant. | | npx -y @lsf-lab/lp-mcp works in the terminal but hangs in Claude Desktop | Claude Desktop needs a restart after editing the config | Quit and reopen Claude Desktop fully. |

Direct CLI

# Show help
npx -y @lsf-lab/lp-mcp --help

# Show version
npx -y @lsf-lab/lp-mcp --version

# Run with env vars (recommended)
LP_API_KEY=ldk_xxx LP_API_URL=https://api.example.com \
  npx -y @lsf-lab/lp-mcp

# Run with flags (NOT recommended for production — visible in ps aux)
npx -y @lsf-lab/lp-mcp \
  --api-key ldk_xxx \
  --api-url https://api.example.com

Requirements

• Node.js ≥ 20 — the bundle targets node20. Older Node versions will fail with cryptic errors.
• An MCP client that supports the stdio transport (Claude Desktop, Cursor, Continue, etc.).
• A valid API key for your @lsf-lab API installation.

Trust signals

• ✅ No source code published — only the bundled, minified dist/lp-mcp.js (~41 KB) ships to npm.
• ✅ Smoke-tested in CI — every release runs a real API call against a staging deployment before publish.
• ✅ Tool surface locked by snapshot test — tools/list output is byte-stable across releases. Any drift fails CI.
• ✅ No secrets logged — API keys and bypass tokens are header-only, never written to stdout, stderr, error messages, or query strings.
• ✅ Structured errors — every tool error includes status, code, and details from the API, not a flat string.
• ✅ Method-aware retry policy — GET/DELETE retry on 5xx, POST/PUT do not (avoids duplicate writes).

Versioning

This package follows Semantic Versioning. Breaking changes only happen at 0.x.0 minor bumps (until 1.0.0) or x.0.0 major bumps (after). Patch releases (0.1.x) are bug-fix-only. See the CHANGELOG before upgrading.

Contributing

This is a private package. Source is not currently public. See CONTRIBUTING.md if you have access to the source repository.

License

Proprietary. See LICENSE.