@lsf-lab/lp-mcp

An MCP server that exposes a lead-engagement, campaign-management, and knowledge-base API to AI agents over stdio. 137 tools. 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.knowledge_search, 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 137 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_. | | 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 137 tools:

| Category | Count | What it does | | -------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- | | Knowledge Engine | 22 | Governed v1 retrieval, ingestion controls, documents, uploads, bases, campaign composition, and activation profiles | | Lead Dossier | 17 | Lead interactions, reviewed facts, dossier documents and material workflows; retrieval uses the canonical Knowledge tools | | Prompts | 14 | Prompt groups and templates, plus workflow monitoring | | 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 | | Campaigns | 8 | Generate social content; create, list, get, update, archive; list and add campaign leads | | 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 | | Brand Presets | 5 | List, get, create, update, and delete brand presets | | Presenters | 5 | List, get, create, update, and delete presenters | | Meetings | 4 | Create, list, get, update | | Pages | 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 |

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

Unified Knowledge retrieval in 0.2.11

Use only lp.knowledge_search and lp.knowledge_fetch for all KB ownership types. The duplicate lp.search_lead_knowledge and lp.fetch_lead_knowledge tools are no longer advertised; migrate their callers to this pair.

Search accepts optional requested_kb_ids and an optional top-level lead_id. A lead context is verified within the credential's account and does not grant permissions. Campaign/taxonomy context remains in target. Empty selections, duplicate IDs, misspelled fields and conflicting targets are rejected instead of discarded.

Fetch revalidates the original credential, lead context, selection and current policy. Its optional lead_id must match the authenticated reference; omitting it restores the original context, not a broader corpus. Restricted platform/tenant information remains subject to the gateway's grants, sensitivity and RLS rules.

Knowledge ingestion controls

lp.knowledge_ingest_document indexes a source as one document block by default. Set segmentation to structural to retain heading, paragraph, list, table and code blocks. URL sources use fetcher: "auto" by default; native and renderer select one path without switching. When content is pasted as inline_text, optional source.source_url records where it came from and is never fetched.

lp.knowledge_merge_document_blocks merges every active block, or a contiguous block_ids subset, into one block. lp.knowledge_retry_ingestion retries a failed ingestion from the same stored source and can explicitly change segmentation or the URL fetcher. lp.knowledge_retry_document_index retries only the failed authored projection of the current document version; it preserves the text and history and never imports the source again. All three require if_match_version and idempotency_key. They return a confirmation proposal for a lead-owned document; other document ownership is refused on the external surface and must be handled in the web app. Permanent document purge has no REST route or MCP tool.

Document reads include the selected segmentation, source-shape warnings, the newest re-index state and URL fetch metadata. Ingestion status includes the newest re-index plus queue_position, which is a 1-based rank only while the job waits for admission and is null afterward. Poll until reindex.state is ready before expecting edited or merged blocks in search.

This branch intentionally retains 0.2.11, which has not been published according to the release owner. Deploy the compatible backend before publishing the client. New context-bound references are rejected by older backend readers; legacy references that cannot prove their lead origin must be refreshed by searching again. Do not disable the existing CI version/existing-version checks or publish an older bundle.

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, pages: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.