feat: remote MCP server support + v0.5.0

.github/workflows/ci.yml

@@ -7,6 +7,103 @@ on:
     branches: [main]
   merge_group:
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.merge_group.ref || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   check:
-    uses: ./.github/workflows/check.yml
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            ~/.cache/uv
+            target
+          key: check-${{ runner.os }}-${{ hashFiles('**/Cargo.lock', 'uv.lock') }}
+          restore-keys: check-${{ runner.os }}-
+      - run: bin/setup
+      - run: bin/check
+
+  integration-app-dev:
+    if: github.event_name == 'merge_group'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            ~/.cache/uv
+            target
+          key: integration-${{ runner.os }}-${{ hashFiles('**/Cargo.lock', 'uv.lock') }}
+          restore-keys: integration-${{ runner.os }}-
+      - run: bin/setup
+      - run: bin/build
+      - name: CLI integration tests
+        run: ./tests/integration.sh
+        env:
+          ASCEND_SERVICE_ACCOUNT_ID: ${{ secrets.APP_DEV_ASCEND_SERVICE_ACCOUNT_ID }}
+          ASCEND_SERVICE_ACCOUNT_KEY: ${{ secrets.APP_DEV_ASCEND_SERVICE_ACCOUNT_KEY }}
+          ASCEND_INSTANCE_API_URL: ${{ secrets.APP_DEV_ASCEND_INSTANCE_API_URL }}
+      - name: Python SDK integration tests
+        run: ./tests/integration.py
+        env:
+          ASCEND_SERVICE_ACCOUNT_ID: ${{ secrets.APP_DEV_ASCEND_SERVICE_ACCOUNT_ID }}
+          ASCEND_SERVICE_ACCOUNT_KEY: ${{ secrets.APP_DEV_ASCEND_SERVICE_ACCOUNT_KEY }}
+          ASCEND_INSTANCE_API_URL: ${{ secrets.APP_DEV_ASCEND_INSTANCE_API_URL }}
+      - name: REST API integration tests
+        run: ./tests/rest.py
+        env:
+          ASCEND_SERVICE_ACCOUNT_ID: ${{ secrets.APP_DEV_ASCEND_SERVICE_ACCOUNT_ID }}
+          ASCEND_SERVICE_ACCOUNT_KEY: ${{ secrets.APP_DEV_ASCEND_SERVICE_ACCOUNT_KEY }}
+          ASCEND_INSTANCE_API_URL: ${{ secrets.APP_DEV_ASCEND_INSTANCE_API_URL }}
+
+  # TODO: enable after APP_ASCEND_SERVICE_ACCOUNT_* secrets are added
+  # integration-app:
+  #   if: github.event_name == 'merge_group'
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-python@v5
+  #       with:
+  #         python-version: "3.13"
+  #     - uses: actions/cache@v4
+  #       with:
+  #         path: |
+  #           ~/.cargo/registry
+  #           ~/.cargo/git
+  #           ~/.cache/uv
+  #           target
+  #         key: integration-${{ runner.os }}-${{ hashFiles('**/Cargo.lock', 'uv.lock') }}
+  #         restore-keys: integration-${{ runner.os }}-
+  #     - run: bin/setup
+  #     - run: bin/build
+  #     - name: CLI integration tests
+  #       run: ./tests/integration.sh
+  #       env:
+  #         ASCEND_SERVICE_ACCOUNT_ID: ${{ secrets.APP_ASCEND_SERVICE_ACCOUNT_ID }}
+  #         ASCEND_SERVICE_ACCOUNT_KEY: ${{ secrets.APP_ASCEND_SERVICE_ACCOUNT_KEY }}
+  #         ASCEND_INSTANCE_API_URL: ${{ secrets.APP_ASCEND_INSTANCE_API_URL }}
+  #     - name: Python SDK integration tests
+  #       run: ./tests/integration.py
+  #       env:
+  #         ASCEND_SERVICE_ACCOUNT_ID: ${{ secrets.APP_ASCEND_SERVICE_ACCOUNT_ID }}
+  #         ASCEND_SERVICE_ACCOUNT_KEY: ${{ secrets.APP_ASCEND_SERVICE_ACCOUNT_KEY }}
+  #         ASCEND_INSTANCE_API_URL: ${{ secrets.APP_ASCEND_INSTANCE_API_URL }}
+  #     - name: REST API integration tests
+  #       run: ./tests/rest.py
+  #       env:
+  #         ASCEND_SERVICE_ACCOUNT_ID: ${{ secrets.APP_ASCEND_SERVICE_ACCOUNT_ID }}
+  #         ASCEND_SERVICE_ACCOUNT_KEY: ${{ secrets.APP_ASCEND_SERVICE_ACCOUNT_KEY }}
+  #         ASCEND_INSTANCE_API_URL: ${{ secrets.APP_ASCEND_INSTANCE_API_URL }}

AGENTS.md

@@ -176,6 +176,16 @@ The `mcp` subcommand starts an MCP (Model Context Protocol) server, exposing Asc
 
 ### usage with Claude Code
 
+**Remote (recommended)** — copy `ASCEND_MCP_URL` from Settings > Instance > MCP Server:
+
+```bash
+claude mcp add --transport http ascend $ASCEND_MCP_URL
+```
+
+Auth is handled automatically via OAuth (browser login). No service account or env vars needed.
+
+**Local (alternative)** — for offline or custom setups:
+
 ```bash
 claude mcp add ascend-tools --transport stdio -- uvx ascend-tools mcp
 ```

docs/QUICKSTART.md

@@ -4,6 +4,30 @@
 
 ascend-tools provides a CLI, Python SDK, Rust SDK, and MCP server for the Ascend REST API. This guide walks you through authentication and your first commands.
 
+## Quick start: remote MCP server
+
+The fastest way to connect an AI assistant to Ascend — no local installation needed:
+
+1. Go to **Settings > Instance > MCP Server** in the Ascend UI
+2. Copy the `ASCEND_MCP_URL`
+3. Run:
+
+```bash
+# Claude Code
+claude mcp add --transport http ascend $ASCEND_MCP_URL
+```
+
+```bash
+# Codex CLI
+codex mcp add --transport http ascend $ASCEND_MCP_URL
+```
+
+Authentication is handled automatically via OAuth (browser login). No service account required. See [Set up the MCP server](mcp.md) for more options.
+
+---
+
+The rest of this guide covers the **local** CLI, SDK, and MCP server setup (requires a service account).
+
 ## Prerequisites
 
 - An Ascend Instance with permission to create service accounts