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 for that operation (not nested under operation) — the MCP schema allows extra top-level properties; for example create_connector needs connector_type and any fields the platform tool expects, alongside operation.

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

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

Capability and permission denials (recommended session)

There is no separate MCP “list my capabilities” tool. Use session tools plus your client’s tool list:

1. loxtep_session → get_current_user — response includes permissions (effective RBAC: resource, action, source, …) and roles. Use this to see what grants you have before calling write operations.
2. loxtep_session → get_current_organization — confirm organization context.
3. Project-scoped facades (loxtep_workflows, loxtep_connections, …) need project_id on each call for project-specific operations. The loxtep_data_products facade includes list_data_products, which is organization-scoped (no project_id; lists catalog data products like GET /dataproducts). Other data-product operations in that facade may still require project_id (see ListTools / schema in your client).
4. ListTools (or equivalent) shows each loxtep_* tool’s parameters and descriptions.

If a tool returns permission denied: compare the message to your get_current_user.permissions entries. Only an org owner/admin can change roles; re-running login does not add grants.

If list_data_products returns Missing required argument: 'project_id': the platform ai microservice behind your MCP URL is still on an older build. That message is thrown only by the legacy project wrapper. Deploy or update the ai Lambda stack that serves /ai/mcp/tools/call (then retry the tool call).

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.

Paid instances (managed / self-hosted): create_instance needs a payment_method_id (UUID) for an org’s already saved payment method. The Customer MCP does not include tools to add cards, bank accounts, or payment methods — those are created in the Loxtep web app (Billing or Account / Payments), usually through the payment processor’s hosted or embedded flow. After the user adds a method in the app, they use that method’s id (from the billing UI or your org’s usual workflow) when calling create_instance.

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/credentials.json** (shared with loxtep login) 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 (e.g. API Gateway) used for auth and for GET /app/stream-url. | | LOXTEP_MCP_TOOLS_BASE_URL | Optional. Lambda Function URL origin for POST /ai/mcp/tools/call (append path automatically). If unset, the client calls GET {LOXTEP API}/app/stream-url?stream=ai/mcp/tools/call to resolve the URL (same as the app). Use when API Gateway returns an empty body for streaming tools. | | LOXTEP_MCP_TOOLS_URL | Optional. Full URL for POST MCP tool calls (overrides base + stream-url resolution). | | LOXTEP_TOKEN_FILE | Custom path for the token file (default ~/.loxtep/credentials.json). | | LOXTEP_AUTH_TOKEN | Provide an access token directly (no refresh; advanced). | | MCP_DEBUG | Set to 1 for extra stderr logging from this server. |

Token refresh

While the MCP server is running, it refreshes the Loxtep access token using the stored refresh token when the access token is at or near expiry (60s buffer), and persists the new pair to your token file (the backend rotates refresh tokens). If a tool call gets 401, it retries once after a refresh when a file-based refresh token exists.

If refresh fails (e.g. refresh token expired after ~30 days) or you only use LOXTEP_AUTH_TOKEN without a refresh token, 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). The same test asserts src/instances-input-properties.ts matches ai/lib/tools/mcp-facade-instances-input-properties.ts (ListTools hints for loxtep_instances / create_instance).

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