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:

{ "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\*\*(defaultus-east-1) when signing is used.

Quickstart

1. Log in (one-time)

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 below for Cursor, Claude Desktop, or other clients.

MCP Setup

Cursor

In Cursor Settings → MCP, or in ~/.cursor/mcp.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):

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

Restart Claude Desktop.

Other stdio-based clients

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:

npx @loxtep/customer-mcp-server login

Testing (package developers)

From this directory, after npm install:

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

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).