MCP Server

@venelx/mcp is an MCP (Model Context Protocol) server that lets AI assistants — Claude Code, Cursor, Kimi Code, and any MCP-compatible client — operate the Venelx platform through its REST API: list projects, trigger builds, check build status, tail logs, list artifacts and workers, diagnose code-signing / GitHub access, and sync local iOS/Android signing credentials.

The server talks to the Venelx API over HTTPS and to your AI client over stdio.

Prerequisites

Node.js ≥ 18
A Venelx account with at least one project
A token — either of:
- Browser login (recommended, nothing to copy-paste) — run npx @venelx/mcp login
- Manual token — create one in the dashboard at Account → API tokens: app.venelx.com/account/tokens

bash

npx @venelx/mcp login

Opens app.venelx.com in your browser. Approve access there and the token is saved to ~/.venelx/mcp-token — the server picks it up automatically, so your MCP client config doesn't need a VENELX_TOKEN env var at all.

Token scopes

Scope	What it allows
`read`	All read-only tools (list projects, status, logs, artifacts, …)
`write`	Everything `read` allows, plus `trigger_build` and the local signing sync tools

Tokens look like vx_.... Treat them like passwords — pass them via environment variables, never commit them. See API tokens for the full lifecycle.

Configuration

Environment variable	Required	Default	Description
`VENELX_TOKEN`	no*	—	Personal API token (`vx_...`). *Not needed after `npx @venelx/mcp login` — falls back to `~/.venelx/mcp-token`.
`VENELX_API_URL`	no	`https://api.venelx.com`	API base URL (self-hosted etc.)

Install & run

Claude Code

bash

claude mcp add venelx --env VENELX_TOKEN=vx_... -- npx -y @venelx/mcp

Skip the --env VENELX_TOKEN=... entirely if you've already run npx @venelx/mcp login.

Cursor

Add to .cursor/mcp.json:

json

{
  "mcpServers": {
    "venelx": {
      "command": "npx",
      "args": ["-y", "@venelx/mcp"],
      "env": {
        "VENELX_TOKEN": "vx_..."
      }
    }
  }
}

Kimi Code / generic MCP client

Same shape — add to your client's MCP JSON config:

json

{
  "mcpServers": {
    "venelx": {
      "command": "npx",
      "args": ["-y", "@venelx/mcp"],
      "env": {
        "VENELX_TOKEN": "vx_...",
        "VENELX_API_URL": "https://api.venelx.com"
      }
    }
  }
}

Local development

bash

git clone <repo> && cd venelx-mcp
npm install
npm run build

Then point your MCP client config at the local build:

json

{
  "mcpServers": {
    "venelx": {
      "command": "node",
      "args": ["/path/to/venelx-mcp/dist/index.js"],
      "env": {
        "VENELX_TOKEN": "vx_..."
      }
    }
  }
}

Tools

Tool	Scope needed	What it does
`list_projects`	read	List projects the token can access (id, name, GitHub URL, platforms, role).
`get_project`	read	Project details plus a GitHub access summary.
`trigger_build`	write	Queue a build for a platform (`ios`, `android`, …). Surfaces `skipReason` (e.g. `signing_not_ready`, `github_token_invalid`).
`build_status`	read	Current pipeline status per platform + the 10 most recent builds.
`tail_logs`	read	Last N lines of a build log (latest build, or a given `buildId`).
`list_artifacts`	read	Build artifacts for a project.
`list_workers`	read	Build workers owned by the account (name, status, capabilities).
`signing_status`	read	Code-signing readiness, optionally per platform (`ios`/`android`).
`github_access`	read	GitHub repo access diagnosis: `githubAccess {ok, reason, message}` + auth source label.
`discover_local_ios_signing`	read	macOS only. List provisioning profiles and Keychain code-signing identities on this machine. Read-only, nothing uploaded.
`sync_local_ios_signing`	write	macOS only. Export the matching Distribution cert + key from Keychain and upload it with the best-matching local provisioning profile(s) as this project's iOS signing credentials.
`discover_local_android_signing`	read	Scan a local project checkout's `android/` dir for a keystore + gradle.properties credentials. Read-only.
`sync_local_android_signing`	write	Upload a local project checkout's release keystore as this project's Android signing credentials.

sync_local_ios_signing only syncs one extra provisioning profile per project today (whichever sub-bundle-ID extension is found locally — typically a share extension). If your app has multiple extension targets, the tool's response lists every extension bundle ID it found so you can see what was skipped.

Troubleshooting

401 Authentication failed — VENELX_TOKEN is missing, wrong, or revoked. Run npx @venelx/mcp login again, or create a new token at Account → API tokens and update your MCP config.
403 Forbidden on trigger_build — your token only has the read scope. Create a token with the write scope.
Could not reach the Venelx API (ECONNREFUSED / ENOTFOUND) — the API base URL is unreachable. Check VENELX_API_URL (defaults to https://api.venelx.com) and your network.
Nothing happens / no output — MCP servers speak JSON-RPC on stdout; run it through your MCP client, not directly in a terminal. Diagnostics are printed to stderr.

Never paste a vx_ token into a chat, a commit, or a client config file that is checked into git. If a token leaks, revoke it immediately in the dashboard.

← API Tokens Reference →