ascend-io · lostmygithubaccount · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026
diff --git a/AGENTS.md b/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
 ```

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
@@ -4,6 +4,28 @@
 
 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
+
+# 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

diff --git a/docs/mcp.md b/docs/mcp.md
@@ -1,14 +1,35 @@
 # Set up the MCP server
 
-Connect AI assistants to Ascend using the ascend-tools MCP server.
+Connect AI assistants to Ascend using the [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server. Exposes 8 tools for managing runtimes and flows. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and other MCP-compatible clients.
 
-## Overview
+## Remote MCP server (recommended)
 
-The `ascend-tools mcp` subcommand starts an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that exposes 8 tools for managing Ascend runtimes and flows. It works with Claude Code, Claude Desktop, Codex CLI, Cursor, and other MCP-compatible clients.
+Every Ascend instance hosts a remote MCP server — no local installation required. Find the URL at **Settings > Instance > MCP Server** in the Ascend UI.
 
-## Set up with Claude Code
+### Claude Code
 
-### Install
+```bash
+# Copy ASCEND_MCP_URL from Settings > Instance > MCP Server
+claude mcp add --transport http ascend $ASCEND_MCP_URL
+```
+
+Authentication is handled automatically via OAuth (browser login). No service account or env vars needed.
+
+### Codex CLI
+
+```bash
+codex mcp add --transport http ascend $ASCEND_MCP_URL
+```
+
+### Other MCP clients
+
+Point your client at the MCP URL from Settings using the **Streamable HTTP** transport. The server supports OAuth 2.1 with PKCE for authentication.
+
+## Local MCP server (alternative)
+
+For offline development, custom configurations, or when you prefer running tools locally.
+
+### Claude Code
 
 ```bash
 claude mcp add ascend-tools -- uvx ascend-tools mcp
@@ -26,19 +47,7 @@ claude mcp add --transport stdio \
   ascend-tools -- uvx ascend-tools mcp
 ```
 
-### Verify
-
-Run `/mcp` inside Claude Code. You should see `ascend-tools` listed with 8 tools.
-
-### Remove
-
-```bash
-claude mcp remove ascend-tools
-```
-
-## Set up with Codex CLI
-
-### Install
+### Codex CLI
 
 ```bash
 codex mcp add ascend-tools -- uvx ascend-tools mcp
@@ -54,32 +63,28 @@ codex mcp add \
   ascend-tools -- uvx ascend-tools mcp
 ```
 
-### Inspect and manage
-
-```bash
-codex mcp get ascend-tools --json
-codex mcp list
-codex mcp remove ascend-tools
-```
-
-## Set up with other MCP clients
-
-### Stdio transport (default)
+### Other transports
 
 ```bash
+# Stdio (default) — communicates over stdin/stdout
 ascend-tools mcp
+
+# HTTP — Streamable HTTP on /mcp endpoint
+ascend-tools mcp --http --bind 127.0.0.1:8000
 ```
 
-Communicates over stdin/stdout. Most MCP clients use this transport.
+### Verify
 
-### HTTP transport
+Run `/mcp` inside Claude Code. You should see `ascend-tools` listed with 8 tools.
+
+### Manage
 
 ```bash
-ascend-tools mcp --http --bind 127.0.0.1:8000
+claude mcp remove ascend-tools
+codex mcp list
+codex mcp remove ascend-tools
 ```
 
-Streamable HTTP on the `/mcp` endpoint. Use for remote or shared deployments, or clients that don't support stdio.
-
 ## Tools reference
 
 ### list_runtimes

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,8 +1,8 @@
 [project]
 name = "ascend-tools"
-version = "0.4.0"
+version = "0.5.0"
 description = "Ascend CLI, SDK, MCP."
-requires-python = ">=3.13"
+requires-python = ">=3.10"
 license = "MIT"
 authors = [{ name = "Cody", email = "cody.peterson@ascend.io" }]
 dependencies = []

diff --git a/src/ascend_tools/__init__.py b/src/ascend_tools/__init__.py
@@ -2,8 +2,9 @@
 
 from ascend_tools.core import Client
 from ascend_tools.core import run as run_cli
+from ascend_tools.core import run_mcp_http
 
-__all__ = ["Client"]
+__all__ = ["Client", "run_mcp_http"]
 
 
 def main() -> None:

diff --git a/src/ascend_tools/ascend-tools-cli/Cargo.toml b/src/ascend_tools/ascend-tools-cli/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ascend-tools-cli"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2024"
 rust-version = "1.88"
 authors = ["Cody <cody.peterson@ascend.io>"]

diff --git a/src/ascend_tools/ascend-tools-cli/src/skill-mcp.md b/src/ascend_tools/ascend-tools-cli/src/skill-mcp.md
@@ -9,40 +9,36 @@ Manage Ascend runtimes, flows, and flow runs via MCP tools.
 
 > Private preview: `ascend-tools` is currently in private preview. Contact your Ascend representative to request access via Service Accounts on your Instance.
 
-## Installation
+## Setup
 
-Add to Claude Code:
+### Remote server (recommended)
+
+Copy the MCP URL from **Settings > Instance > MCP Server** in the Ascend UI, then:
 
 ```bash
-claude mcp add --transport stdio ascend-tools -- uvx ascend-tools mcp
+claude mcp add --transport http ascend $ASCEND_MCP_URL
 ```
 
-If env vars are not inherited from your shell, pass them explicitly:
+Authentication is handled automatically via OAuth. No service account or env vars needed.
 
-```bash
-claude mcp add --transport stdio \
-  -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" \
-  ascend-tools -- uvx ascend-tools mcp
-```
+### Local server (alternative)
 
-Upgrade to the latest version (if stale behavior appears after a release):
+For offline development or custom configurations:
 
 ```bash
-uvx --refresh ascend-tools --version
+claude mcp add --transport stdio ascend-tools -- uvx ascend-tools mcp
 ```
 
-## Authentication
-
-Set three environment variables (from Ascend UI > Settings > Users > Create Service Account):
+Requires service account env vars (from Ascend UI > Settings > Users > Create Service Account):
 
 ```bash
 export ASCEND_SERVICE_ACCOUNT_ID="asc-sa-..."
 export ASCEND_SERVICE_ACCOUNT_KEY="..."
-export ASCEND_INSTANCE_API_URL="https://<instance-name>.api.instance.ascend.io"
+export ASCEND_INSTANCE_API_URL="https://api.<instance>.ascend.io"
 ```
 
+If env vars are not inherited from your shell, pass them explicitly to `claude mcp add` with `-e`.
+
 ## Tools
 
 ### list_runtimes

diff --git a/src/ascend_tools/ascend-tools-core/Cargo.toml b/src/ascend_tools/ascend-tools-core/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ascend-tools-core"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2024"
 rust-version = "1.88"
 authors = ["Cody <cody.peterson@ascend.io>"]

diff --git a/src/ascend_tools/ascend-tools-mcp/Cargo.toml b/src/ascend_tools/ascend-tools-mcp/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ascend-tools-mcp"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2024"
 rust-version = "1.88"
 authors = ["Cody <cody.peterson@ascend.io>"]