Connxio CLI

Connxio CLI provides the connxio command and an MCP server for Connxio management APIs.

The current implementation focuses on MCP usage through:

connxio mcp serve

Prerequisites

• Node.js 24 or newer

• Connxio OAuth client credentials

• A Connxio subscription-scoped API key for each subscription context you want to use

Related MCP server: Coolify MCP Server

Install

Install the CLI globally from npm:

npm i -g @connxio/cli

Verify installation:

connxio --help

Configure OAuth

connxio auth configure

You will be prompted for:

• OAuth client id

• OAuth scope, defaulting to api://connxio/.default

• OAuth client secret

Check status:

connxio auth status

Clear OAuth configuration:

connxio auth clear

You can also configure OAuth with environment variables:

CONNXIO_OAUTH_CLIENT_ID="<client-id>"
CONNXIO_OAUTH_CLIENT_SECRET="<client-secret>"
CONNXIO_OAUTH_TOKEN_URL="https://api.connxio.com/oauth/token"
CONNXIO_OAUTH_SCOPE="api://connxio/.default"

CONNXIO_OAUTH_TOKEN_URL and CONNXIO_OAUTH_SCOPE are optional overrides.

Configure Contexts

A context represents one Connxio subscription. Connxio API keys are subscription-scoped, so add one context for each subscription you want to use.

connxio context add

The CLI calls /v2/subscriptions/current with the provided API key and stores the subscription/company metadata locally. API keys are stored through the credential abstraction, not in config.json.

List contexts:

connxio context list

Set a default context:

connxio context default <context-id>

Remove a context:

connxio context remove <context-id>

Register With VS Code

VS Code 1.99+ supports MCP servers natively via GitHub Copilot agent mode.

Option 1 — user settings (all projects)

Open the command palette (Ctrl+Shift+P/Cmd+Shift+P) and select MCP: Add server.

Select stdio transport, connxio mcp serve as the command, and set the name to connxio. This will create a user-level MCP server registration that is available in all projects.

Alternatively, edit the user level mcp.json config file directly. Open the command palette and select MCP: Open User Configuration, then add:

{
  "servers": {
    "connxio": {
      "type": "stdio",
      "command": "connxio",
      "args": ["mcp", "serve"]
    }
  }
}

Option 2 — workspace settings (this project only)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "connxio": {
      "type": "stdio",
      "command": "connxio",
      "args": ["mcp", "serve"]
    }
  }
}

The Connxio MCP server will now be available when you open this project in VS Code.

If you need to pass environment variables (e.g. for OAuth or a custom API base URL), add an env block:

{
  "servers": {
    "connxio": {
      "type": "stdio",
      "command": "connxio",
      "args": ["mcp", "serve"],
      "env": {
        "CONNXIO_OAUTH_CLIENT_ID": "<client-id>",
        "CONNXIO_OAUTH_CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}

Do not commit files containing OAuth client secrets to source control.

Register With Claude Code

Register the installed MCP server:

claude mcp add --transport stdio connxio -- connxio mcp serve

To register the MCP server at user level (available in all projects), add --scope user:

claude mcp add --scope user --transport stdio connxio -- connxio mcp serve

Verify registration:

claude mcp list

If you need to replace an existing registration:

claude mcp remove connxio
claude mcp add --transport stdio connxio -- connxio mcp serve

API Base URL

The default API base URL is:

https://api.connxio.com

Override it per context:

connxio context add --base-url http://localhost:5119/api

Or with an environment variable:

CONNXIO_API_BASE_URL="http://localhost:5119/api"

For localhost development with self-signed HTTPS certificates, the CLI automatically allows insecure TLS for localhost URLs. For other local development endpoints, use:

CONNXIO_INSECURE_TLS=true

Do not use insecure TLS settings in production.

Run Diagnostics

connxio mcp doctor

For HTTP troubleshooting, enable redacted request diagnostics:

CONNXIO_DEBUG_HTTP=true connxio mcp doctor

MCP Tools

The MCP server exposes Connxio v2 management operations and v3 action-based integrations, schemas, performance metrics, persisted errors, and testing.

Context and subscription tools:

• list_contexts

• get_current_context

• list_subscriptions

• get_current_subscription

Integration tools:

• list_integrations

• get_integration

• create_integration

• create_integration_no_validation

• update_integration

• delete_integration

All integration tools accept apiVersion: "v2" | "v3" (default: "v2"). Choose "v3" for action-based integrations. The API derives action-based mode from triggers or actions; isActionBased is computed, not a writable flag. Integration write bodies accept optional archived (boolean, API default false), which is forwarded along with the other configuration properties. The v3 create tools upsert; the no-validation variant skips graph validation and disables invalid configurations.

Code component tools:

• list_code_components

• get_code_component

• get_code_component_versions

• create_code_component

• deprecate_code_component

• rename_code_component

• delete_code_component

Environment variable tools:

• list_environment_variables

• get_environment_variable

• create_environment_variable

• delete_environment_variable

Security configuration tools:

• list_security_configs

• get_security_config

• create_security_config

• delete_security_config

Schema tools (v3, scoped to the current company):

• list_schemas — latest metadata, without content

• get_schema — latest version with content

• get_schema_versions — all versions with content, newest first

• get_schema_content — content for id and schemaVersion

• upload_schema — create a schema or add a new version

• deprecate_schema — toggle a version's deprecated state; calling again restores it

• delete_schema — permanently delete all versions; fails if an integration references the schema

upload_schema accepts a schema object with id, name, version, type, and base64-encoded content. Optional metadata: description, webhookConnectionId, originalFilename, and uploadedBy. Versions cannot be overwritten; an existing schema's name and type must match.

Performance and persisted error tools (v3):

• list_company_performance_metrics

• list_subscription_performance_metrics

• list_integration_performance_metrics

• get_interchange_performance_metric

• list_subscription_errors

• list_integration_errors

• get_interchange_error

List tools accept optional from and to ISO 8601 timestamps with UTC offsets, skip (0–100,000; default 0), and size (1–1,000; default 100). They return one API page including counts and hasNextPage; request the next page by increasing skip by size. Performance dates default to the last 24 hours; omitted error dates include all retained errors. Integration lists require integrationId. Interchange lookups require interchangeId and do not take date or paging filters.

Performance company and integration queries cover subscriptions within the current company. Persisted error queries are limited to the current subscription. An empty integration error page can also mean the integration does not exist.

Testing tools (v3, scoped to the current subscription):

• list_test_groups

• get_test_group

• create_test_group

• update_test_group

• delete_test_group

• upload_test_file

• get_test_file — uploaded file metadata

• download_test_file — original bytes saved to a new local file

• start_test_run

• list_test_runs

• get_test_run

Create/update tools accept a group object containing name, a nonempty list of unique integrationIds, and optional assertions mapping integration IDs to node IDs to CxMaL expressions. Updating replaces these fields: omitted or empty assertions clears existing assertions. On a 409, reload the group before editing again. Deleting a group cleans retained run history and requires confirm: true.

Upload one nonempty fixture per integration using groupId, integrationId, and either source: { "type": "text", "content": "..." } or source: { "type": "file", "filePath": "/path/to/fixture" }. Text is sent as UTF-8; local file bytes are sent verbatim. Optional fileName, contentType, and isBinary override inferred metadata. Local files infer JSON, XML, plain text, or binary content types from their extension; binary defaults to true for application/octet-stream. Inline text defaults to plain text and the API's {integrationId}.txt filename. For example, use contentType: "application/json" and fileName: "input.json" for inline JSON. JSON/XML content is never wrapped in a JSON string.

download_test_file requires a local destination filePath; its parent directory must exist. It returns an absolute path and byte count, preserves original bytes, and refuses to overwrite an existing file. Local paths refer to the machine running the MCP server.

start_test_run starts real integration execution and requires all group fixtures before submission. It returns run metadata immediately and never automatically retries a failed submission. Optional connxioApiKeyId is an API key ID, never a secret. Check history before manually resubmitting after an uncertain response.

list_test_runs returns one API page with counts and hasNextPage. Optional skip ranges from 0–100,000 (default 0); size ranges from 1–1,000 (default 100). Increase skip by size to continue. History contains run metadata; use get_test_run for evaluated results.

get_test_run takes groupId, runId, optional waitSeconds (0–60, MCP default 0), and optional includeStatusEvents (API default false). It performs one lookup or bounded wait, without automatic polling. Inspect run.status and run.isComplete: HTTP 202 means running; HTTP 200 includes completed failures. Status values are InProgress, Passed, Failed, Terminated, and Timeout. Assertion verdicts are returned even without detailed events; disconnecting a wait does not cancel execution.

Standalone integration testing tools (v3, scoped to the current company and subscription):

• upload_integration_test_file

• get_integration_test_file — standalone fixture metadata

• download_integration_test_file

• start_integration_test_run

• list_integration_test_runs

• get_integration_test_run

These tools use integrationId without a groupId and support both legacy and action-based integrations through /v3/integrations/{integrationId}/testfile and /testruns. Standalone fixtures and history are separate from group fixtures and history; they share the portal's standalone test storage. In standalone run metadata, testGroupId equals integrationId. Configuration snapshots stay internal to the API.

File upload/download inputs and byte-preservation behavior match the group tools. Uploads require contextId; text/file source, contentType, fileName, and isBinary work identically. The API normalizes stored filenames to printable ASCII basenames. Downloads require a new destination filePath and never overwrite an existing file.

start_integration_test_run requires contextId and a nonempty saved standalone fixture. Missing/empty fixtures fail before execution. Optional triggerId selects an existing trigger and is not necessarily a GUID. Omitting triggerId skips inbound processing, matching the portal; supply it to run the selected trigger. Optional connxioApiKeyId is a key ID, never a secret. Submission returns run metadata and resultsUrl without waiting for completion or automatically retrying.

list_integration_test_runs uses the same skip/size bounds and returns one page with paging metadata, including portal-created standalone runs. get_integration_test_run requires integrationId and runId, defaults to waitSeconds: 0, supports waits up to 60 seconds, and accepts includeStatusEvents. Inspect run.status and run.isComplete; a completed failure remains a successful HTTP 200 response, while an unfinished run returns 202. Disconnecting a wait does not cancel execution.

Write tools require contextId. Destructive tools require contextId and confirm: true.

/messages operations are intentionally not exposed yet.

Local Config Files

Non-secret config is stored in:

• macOS/Linux: ${XDG_CONFIG_HOME:-~/.config}/connxio/config.json

• Windows: %APPDATA%\connxio\config.json

Secrets are stored through the CLI credential abstraction. The CLI now uses the OS keyring when available and falls back to ${XDG_CONFIG_HOME:-~/.config}/connxio/credentials.json on macOS/Linux or %APPDATA%\connxio\credentials.json on Windows when secure storage is unavailable.

If you already have secrets in credentials.json, the CLI migrates them into the OS keyring lazily as they are used and removes the legacy file entries after a successful migration.