npm package: @loxtep/customer-mcp-server
Description: Customer MCP proxy: login via app UI, stdio server that forwards tool calls to Loxtep API
Author: Loxtep Team
Latest version: 1.0.25

# Loxtep Customer MCP Server

Connect Cursor, Claude Desktop, or any MCP-compatible client to your Loxtep
account. Sign in once through the Loxtep app; the server stores your session and
runs Loxtep tools on your behalf.

## Tools (what you’ll see in your client)

Your MCP client lists tools grouped by area, for example `loxtep_session`,
`loxtep_projects`, `loxtep_workflows`, and others.

Each tool call includes:

- `**operation**` (required): which action to run, such as `list_workflows`,
  `get_current_organization`, or `search_catalog`.
- **Other fields**: parameters that action needs (for example `project_id`,
  filters, or request bodies), as shown in your client’s tool schema.

**Example:** list workflows in a project — tool name `loxtep_workflows`,
arguments:

```json
{ "operation": "list_workflows", "project_id": "<your-project-uuid>" }
```

## Prerequisites

- **Access:** Your Loxtep user must be allowed to use MCP tools (typically
  **owner**, **org admin**, or **developer**). If tools return **403**, ask your
  organization owner to adjust your role.
- **Node.js** 18 or newer.

Optional: set `**LOXTEP_AWS_REGION`** or `**AWS_REGION\*\*`(default`us-east-1`)
when signing is used.

## Quickstart

### 1. Log in (one-time)

```bash
npx @loxtep/customer-mcp-server login
```

Your browser opens the Loxtep app. Complete sign-in (including MFA if required).
Tokens are saved to `**~/.loxtep/customer-mcp.json**` with restricted file
permissions.

### 2. Add the server to your MCP client

See **[MCP Setup](#mcp-setup)** below for Cursor, Claude Desktop, or other
clients.

---

## MCP Setup

### Cursor

In **Cursor Settings → MCP**, or in `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "loxtep": {
      "command": "npx",
      "args": ["@loxtep/customer-mcp-server"]
    }
  }
}
```

Restart Cursor. Loxtep tools should appear in the MCP tools list.

### Claude Desktop

Edit `**~/.claude/mcp.json**` (macOS/Linux) or `**%APPDATA%\.claude\mcp.json**`
(Windows):

```json
{
  "mcpServers": {
    "loxtep": {
      "command": "npx",
      "args": ["@loxtep/customer-mcp-server"]
    }
  }
}
```

Restart Claude Desktop.

### Other stdio-based clients

```bash
npx @loxtep/customer-mcp-server
```

Or install globally and run `customer-mcp-server`, or use `pnpm exec` /
`npm exec` from a local install—whichever matches your client’s docs.

---

## Environment variables (optional)

| Variable                   | Purpose                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------- |
| `LOXTEP_ENV` or `NODE_ENV` | Use `dev` / `development` for Loxtep **dev** app and API URLs; otherwise **production** defaults apply. |
| `LOXTEP_APP_URL`           | Override app URL used at login.                                                                         |
| `LOXTEP_API_BASE_URL`      | Override API base URL.                                                                                  |
| `LOXTEP_TOKEN_FILE`        | Custom path for the token file (default `~/.loxtep/customer-mcp.json`).                                 |
| `LOXTEP_AUTH_TOKEN`        | Provide an access token directly (no refresh; advanced).                                                |
| `MCP_DEBUG`                | Set to `1` for extra stderr logging from this server.                                                   |

---

## Security

- Install and run only the published package `**@loxtep/customer-mcp-server`\*\*
  from npm.
- Do not share `**~/.loxtep/customer-mcp.json**` or commit it to git.
- Login uses `**127.0.0.1:38473**`; if that port is busy, login will report an
  error.

---

## Token refresh

If the app session expires, run login again:

```bash
npx @loxtep/customer-mcp-server login
```

---

## Testing (package developers)

From this directory, after `npm install`:

```bash
npm test
```

Vitest covers facade resolution, HTTP error mapping for `callToolApi`, and parity
of `src/facades.ts` with `platform-backend/ai/lib/tools/mcp-facades.ts` (via a
Jest test in the `ai` package: `lib/tools/customer-mcp-facades-parity.test.ts`).

Optional live check against a deployed API (JWT only): see
`platform-backend/ai/api/mcp/tools/call/POST/test/mcp-live-smoke.test.ts` and
set `LOXTEP_MCP_SMOKE=1` plus `LOXTEP_API_BASE_URL` and `LOXTEP_AUTH_TOKEN`.

---

## Troubleshooting

```bash
MCP_DEBUG=1 npx @loxtep/customer-mcp-server
```

Check:

1. You have run `**login**` at least once.
2. Your Loxtep role allows MCP tool use (see **Prerequisites**).
3. `**~/.loxtep/customer-mcp.json`\*\* exists (or your `LOXTEP_TOKEN_FILE`
   path).
4. Your MCP config runs `**npx @loxtep/customer-mcp-server**` (or an equivalent
   path to this package).