ascend-tools 1.0.0

Ascend CLI, SDK, MCP.

ascend-tools

CLI, SDK, and MCP server for the Ascend Instance web API.

Install

Pre-built binaries are available for Linux and macOS. Windows users should use Linux/macOS.

uv tool install ascend-tools

Authentication

Set three environment variables (from Ascend UI > Settings > Users > Create Service Account):

export ASCEND_SERVICE_ACCOUNT_ID="asc-sa-..."
export ASCEND_SERVICE_ACCOUNT_KEY="..."
export ASCEND_INSTANCE_API_URL="https://<instance-name>.api.instance.ascend.io"

CLI

List workspaces:

ascend-tools workspace list

Get a workspace:

ascend-tools workspace get "My Workspace"

Pause / resume a workspace:

ascend-tools workspace pause "My Workspace"
ascend-tools workspace resume "My Workspace"

List and run flows:

ascend-tools flow list --workspace "My Workspace"
ascend-tools flow run <FLOW_NAME> --workspace "My Workspace"
ascend-tools flow run <FLOW_NAME> --workspace "My Workspace" --resume
ascend-tools flow run <FLOW_NAME> --workspace "My Workspace" --spec '{"full_refresh": true}'

Deployments work the same way:

ascend-tools deployment list
ascend-tools deployment get "My Deployment"
ascend-tools flow list --deployment "My Deployment"

JSON output:

ascend-tools -o json workspace list

Interactive TUI

Chat with Otto in a full-screen terminal interface:

ascend-tools otto tui
ascend-tools otto tui --workspace "My Workspace"

Vi keybindings by default. Type /help for commands, /emacs to switch modes. Alt+Enter for multi-line input. Up/Down for input history.

Python SDK

from ascend_tools import Client

client = Client()  # reads from env vars
client.list_workspaces()
client.run_flow(flow="sales", workspace="My Workspace")

MCP server

Start an MCP server for AI assistants (Claude Code, Claude Desktop, Cursor, etc.).

Stdio transport (default):

ascend-tools mcp

HTTP transport:

ascend-tools mcp --http --bind 127.0.0.1:8000

Claude Code setup

claude mcp add --transport stdio ascend-tools-dev -- uvx ascend-tools mcp

The Ascend auth env vars are inherited from your shell. Verify with /mcp inside Claude Code. If Claude is launched without your shell env, add vars explicitly:

claude mcp add --transport stdio ascend-tools-dev \
  -e ASCEND_SERVICE_ACCOUNT_ID="$ASCEND_SERVICE_ACCOUNT_ID" \
  -e ASCEND_SERVICE_ACCOUNT_KEY="$ASCEND_SERVICE_ACCOUNT_KEY" \
  -e ASCEND_INSTANCE_API_URL="$ASCEND_INSTANCE_API_URL" \
  -- uvx ascend-tools mcp

Codex CLI setup

codex mcp add ascend-tools-dev -- uvx ascend-tools mcp

If Codex is launched without your shell env, add vars explicitly:

codex mcp add \
  --env "ASCEND_SERVICE_ACCOUNT_ID=$ASCEND_SERVICE_ACCOUNT_ID" \
  --env "ASCEND_SERVICE_ACCOUNT_KEY=$ASCEND_SERVICE_ACCOUNT_KEY" \
  --env "ASCEND_INSTANCE_API_URL=$ASCEND_INSTANCE_API_URL" \
  ascend-tools-dev -- uvx ascend-tools mcp

Inspect the MCP server config:

codex mcp get ascend-tools-dev --json

List all configured MCP servers:

codex mcp list

Remove the config:

codex mcp remove ascend-tools-dev

The Ascend auth env vars are inherited from your shell when Codex launches the server. If you have stale MCP behavior after updating code, run this once to refresh the uvx cache:

uvx --refresh ascend-tools --version

If Codex MCP startup fails with connection closed: initialize response, refresh once and re-add:

uvx --refresh ascend-tools --version

Tools

Tool	Description
list_workspaces	List workspaces with optional filters
get_workspace	Get a workspace by title
create_workspace	Create a new workspace
update_workspace	Update a workspace
pause_workspace	Pause a workspace
resume_workspace	Resume a paused workspace
delete_workspace	Delete a workspace
list_deployments	List deployments with optional filters
get_deployment	Get a deployment by title
create_deployment	Create a new deployment
update_deployment	Update a deployment
pause_deployment_automations	Pause automations on a deployment
resume_deployment_automations	Resume automations on a deployment
delete_deployment	Delete a deployment
list_environments	List environments
list_projects	List projects
list_profiles	List profiles for a workspace, deployment, or project+branch
list_flows	List flows in a workspace or deployment
run_flow	Trigger a flow run
list_flow_runs	List flow runs with filters
get_flow_run	Get a flow run by name
list_otto_providers	List Otto providers and models
otto	Chat with Otto AI assistant

Skills

Install reference skills for AI coding assistants (Claude Code, Codex, etc.):

ascend-tools skill install --target .claude/skills --all

Available skills: --cli (default), --python, --mcp, --all.