npm package: @lpextend/mcp-server
Description: LivePerson Conversational Cloud MCP Server — 62 tools for managing bots, knowledge bases, campaigns, conversations, and more via AI assistants
Latest version: 0.10.4

# LivePerson MCP Server

MCP server that gives AI coding assistants direct access to LivePerson's Conversational Cloud APIs. Manage knowledge bases, bots, conversations, users, skills, and more — through natural language.

Works with any AI tool that supports the [Model Context Protocol](https://modelcontextprotocol.io): **Claude Code**, **OpenAI Codex**, **Gemini CLI**, **VS Code Copilot**, **Cursor**, **Windsurf**, and others.

## Prerequisites

- Node.js 18+
- A LivePerson account with a **bot-type user** and API keys

## Setup

### 1. Create a bot user in LivePerson

1. Go to **Conversational Cloud > Manage > Users**
2. Create a new user (e.g. `claude-mcp`)
3. Set type to **Bot**
4. Assign the **Admin** profile (or a custom profile with the permissions you need)
5. Generate **API keys** for the user — you'll get:
   - App Key
   - Secret
   - Access Token
   - Access Token Secret

### 2. Install and configure

```bash
npx @lpextend/mcp-server --setup
```

This prompts for your credentials and saves them to `~/.config/lp-mcp/.env`.

Or create the file manually:

```env
LP_ACCOUNT_ID=12345678
LP_LOGIN_NAME=claude-mcp
LP_APP_KEY=your-app-key
LP_SECRET=your-secret
LP_ACCESS_TOKEN=your-access-token
LP_ACCESS_TOKEN_SECRET=your-access-token-secret
```

### 3. Connect to your AI tool

#### Claude Code

```bash
claude mcp add liveperson -- npx @lpextend/mcp-server
```

Or add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "liveperson": {
      "command": "npx",
      "args": ["@lpextend/mcp-server"]
    }
  }
}
```

#### OpenAI Codex

```bash
codex mcp add liveperson -- npx @lpextend/mcp-server
```

Or add to `~/.codex/config.toml`:

```toml
[mcp_servers.liveperson]
command = "npx"
args = ["@lpextend/mcp-server"]
```

#### Gemini CLI

Add to your `settings.json`:

```json
{
  "mcpServers": {
    "liveperson": {
      "command": "npx",
      "args": ["@lpextend/mcp-server"]
    }
  }
}
```

#### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "liveperson": {
      "type": "stdio",
      "command": "npx",
      "args": ["@lpextend/mcp-server"]
    }
  }
}
```

#### Cursor / Windsurf

Both support MCP servers through their settings UI. Add a new MCP server with:
- **Command:** `npx`
- **Args:** `@lpextend/mcp-server`

## Credential Loading

The server loads credentials in this priority order:

1. **System environment variables** (highest priority)
2. **Project-level** `.env` file (in the `lp-extend-mcp/` directory)
3. **User-level** `~/.config/lp-mcp/.env` (from `--setup`)

This means you can override the global config per-project by placing a `.env` file in the project directory.

## Optional: Web Crawl (Playwright)

The `web_crawl` tool extracts text content from any webpage — including JavaScript-rendered SPAs that standard HTTP fetching can't handle. It uses headless Chromium via Playwright to fully render pages before extraction.

This is especially useful for the **Website → Knowledge Base** workflow: crawl a brand's website, extract content, and feed it into `composite_kai_kb` to create a fully populated knowledge base.

To enable it, install Playwright after the main install:

```bash
npm install playwright
npx playwright install chromium
```

If Playwright is not installed, the tool is silently omitted — all other tools work normally.

## Available Tools

62 tools across 10 modules (+ 1 optional). Each tool uses an `action` parameter to select operations. See **[TOOLS.md](TOOLS.md)** for the full reference with all actions and parameters.

| Module | Tools | What they do |
|--------|-------|--------------|
| **Account Config** | `ac_skills`, `ac_users`, `ac_lobs`, `ac_lookup`, `ac_entry_points`, `ac_windows`, `ac_campaigns`, `ac_engagements` | CRUD for all account resources |
| **Account Config (Extended)** | `ac_workdays`, `ac_special_occasions`, `ac_auto_messages`, `ac_predefined_content`, `ac_predefined_categories`, `ac_audit_trail`, `ac_agent_status`, `ac_shift_status`, `ac_agent_survey` | Working hours, holidays, canned responses, audit trail, agent status |
| **Conversation Builder** | `cb_bots`, `cb_deploy`, `cb_dialogs`, `cb_interactions`, `cb_integrations`, `cb_global_functions`, `cb_lookup`, `cb_logs` | Bot management, deployment, dialog building |
| **AI Studio** | `ai_flows`, `ai_prompts`, `ai_conversations`, `ai_categories`, `ai_knowledge`, `ai_simulations`, `ai_evaluation`, `ai_routing`, `ai_lookup` | Flow CRUD, testing, evaluation, routing |
| **Knowledge AI** | `kai_knowledgebases`, `kai_articles` | KB and article management |
| **Conversations** | `conv_manage` | Search, transcript, close, close all, transfer, send message |
| **Auth** | `auth_tokens`, `auth_apps` | OAuth tokens, app installations |
| **Composites** | `composite_campaign_stack`, `composite_kai_kb`, `composite_web_crawl_to_kb`, `composite_wire_cb_bot`, `composite_deploy_bot`, `cb_bot_health_check`, `workflow_create_demo`, `composite_bot_summary`, `composite_flow_summary`, `composite_bot_audit`, `composite_teardown_demo`, `composite_cleanup_campaigns`, `composite_describe_flow`, `composite_describe_bot`, `composite_flow_audit`, `composite_optimise_kb`, `composite_route_test_suite`, `composite_backup_account` | Multi-step workflows, summaries, audits, optimisation, testing, backup, and teardown |
| **Demo Wizard** | `demo_get_creation_plan`, `demo_list_available_bot_users`, `demo_get_component_info`, `demo_list_flow_types` | Demo creation planning |
| **Web Crawl** *(optional)* | `web_crawl` | Extract content from any webpage including SPAs (requires Playwright) |

## Usage

Once connected, just talk to your AI assistant in natural language. The MCP server gives it the tools — you describe what you want done.

### Exploring your account

Start by asking questions about what's in your account:

```
"Show me all my skills"
"List all bots and their running status"
"What knowledge bases do I have?"
"Show me all bot users and which bots they're assigned to"
"What profiles are available in my account?"
```

### Website to Knowledge Base

One of the most powerful workflows — turn any website into a KAI knowledge base ready for bot consumption:

```
"Review https://brand.com/help and create a knowledge base called 'Brand FAQ'
 with articles covering their main help topics"
```

The AI will:
1. Fetch and analyse the website pages
2. Extract key topics and content
3. Create a new knowledge base
4. Generate articles with properly formatted titles (< 300 chars), summaries (< 1,000 chars), and details (< 10,000 chars)
5. Batch-create all articles in one go

This is particularly useful for **demo prep** — quickly spin up a realistic KB from a prospect's website.

### Bot management

Understand and manage your Conversation Builder bots:

```
"Which user account is the 'Sales Bot' using, and what skill is it assigned to?"
"The FAQ Bot is stopped — start it"
"Assign bot user 'bot-agent-02' to the Support Bot"
"Show me all bots in the 'Production' bot group"
```

### Conversation operations

Manage live and historical conversations — especially useful for demo cleanup:

```
"Close all open conversations on the 'Test' skill"
"Transfer conversation abc-123-def to the 'VIP Support' skill"
"Show me the transcript for conversation abc-123-def"
"Find all open conversations from the last 24 hours"
```

### Account setup and configuration

Set up skills, users, and structure for demos or new deployments:

```
"Create skills called 'Sales', 'Support', and 'VIP'"
"Show me all users with the 'Bot' type"
"What agent groups exist and who's in them?"
"List all lines of business"
```

### Chaining actions

The real power is in combining multiple steps with a single instruction:

```
"Set up a demo account: create skills 'Sales', 'Support', and 'VIP',
 then show me available bot users I can assign to each"
```

```
"Review https://acme.com/faq, create a KB called 'Acme FAQ',
 then check if the FAQ Bot is running and start it if it's not"
```

```
"Find all open conversations on the 'Test' skill, close them,
 then show me the 'Test' skill details to confirm it's clean"
```

### Tips

- **Be specific with names** — say "the 'Sales Bot'" not just "the bot", especially if you have multiple
- **Ask questions first** — if you're not sure what's in your account, ask the AI to list things before making changes
- **Use it for auditing** — "Show me which bots are stopped" or "Which bot users don't have any bots assigned?"
- **Destructive actions get confirmed** — the AI will confirm before closing conversations, stopping bots, etc.

## Authentication

The server authenticates using LP's **Application Login** API (bot user with API keys). It handles:

- Bearer token acquisition and caching
- Automatic token refresh before expiry
- Retry on 401 (expired token)
- CB/KAI 2-step auth flow (bearer → apiAccessToken + organizationId)

All transparent — you just use the tools.

## Development

If you want to work on the MCP server itself (add tools, fix bugs, etc.):

```bash
git clone https://github.com/lpdb2024/lp-extend-mcp.git
cd lp-extend-mcp
npm install
copy .env.example .env  # Add your credentials
npm run build
```

Then add a `.mcp.json` file **in the root of whatever project you open in your AI tool**. This tells the tool how to start the server:

```json
{
  "mcpServers": {
    "liveperson": {
      "command": "node",
      "args": ["C:/path/to/lp-extend-mcp/dist/index.js"]
    }
  }
}
```

Or register it globally (Claude Code) so it's available in every project:

```bash
claude mcp add --scope user liveperson -- node C:\path\to\lp-extend-mcp\dist\index.js
```

You don't run the server yourself — your AI tool spawns it automatically when it needs to call a tool. The config just tells it which command to run.

To test the server manually without an AI tool, use the MCP Inspector:

```bash
npm run inspect
```

## License

MIT