Connect your AI assistant#

Astralyx is an MCP server at https://console.astralyx.cloud/mcp. Connect it to Claude, Claude Code, ChatGPT, Cursor, VS Code or any other MCP client, then ask in plain language: "Why is my run train-42 waiting?", "Which machines have free GPUs?", "Deploy Qwen 2.5 7B and ask it to summarise this paragraph", "Start an environment with one GPU and tell me how to SSH in".

The assistant acts as you: in your workspaces, with your role in each, and never more — what you cannot do in the console, it cannot do. It is one more way in, next to the console, the astra command line and the API.

Before you begin#

An Astralyx account and a workspace (see the quick start).
An assistant that supports remote MCP servers over HTTP. Every client below signs you in with OAuth; for one that does not, use an API token.

Connect#

When the assistant connects, it opens the console. Sign in as usual (password, single sign-on, Google or GitHub), then decide on the Connect an app page:

Who asks: the app's name, how it identified itself, and the address it sends you back to. Allow only an app you are connecting right now.
What it may do: Read only, Read and write, or Read, write and admin actions (details).
Which tools it sees: groups of tools (toolsets); fewer tools leave the assistant more room to think.
Where: every workspace you can use, or only one. With several, you can pick the workspace its tools use when you name none.

Choose Allow: you are sent back to the assistant, connected.

ClaudeClaude CodeChatGPTCursorVS Code

In claude.ai, the desktop app or the mobile app:

Open Customize → Connectors and choose Add custom connector. On a Team or Enterprise plan, an owner adds it once under Organization settings → Connectors; members then choose Connect.
Name it Astralyx, enter https://console.astralyx.cloud/mcp and choose Add.
Choose Connect. The console opens: approve it there.
In a conversation, turn it on from the + menu → Connectors.

$ claude mcp add --transport http astralyx https://console.astralyx.cloud/mcp

Add --scope user to have it in every project. Then, in Claude Code, run /mcp, choose astralyx and Authenticate: your browser opens the console; approve it there.

In ChatGPT, open Settings → Security and login and turn on Developer mode. Its availability depends on your plan and your workspace's policy.
Add a connection (Apps and connectors, then +): name it Astralyx, enter https://console.astralyx.cloud/mcp with OAuth, and create it. The console opens: approve it there.
Start a new conversation and add the connection from the tools menu.

ChatGPT asks you before each tool that changes something.

In ~/.cursor/mcp.json (every project) or a project's .cursor/mcp.json:

mcp.json

{
  "mcpServers": {
    "astralyx": { "url": "https://console.astralyx.cloud/mcp" }
  }
}

In Cursor Settings → MCP, Astralyx shows as needing a login: choose it, and approve it in the console.

In .vscode/mcp.json, or with MCP: Add Server → HTTP in the command palette:

.vscode/mcp.json

{
  "servers": {
    "astralyx": { "type": "http", "url": "https://console.astralyx.cloud/mcp" }
  }
}

Start it from the file or the MCP view, and approve it in the console.

Other clients and scripts#

A client without OAuth — or a script, or a CI job — sends a personal API token instead:

$ claude mcp add --transport http astralyx https://console.astralyx.cloud/mcp \
    --header "Authorization: Bearer ast_pat_…"

A token acts as you everywhere you have access (or only in the workspace it is scoped to), with every level of access. Two headers narrow it:

Header	Example	Effect
`Astralyx-Toolsets`	`runs,eos`	Only these toolsets (and `context`). `all` turns every one on.
`Astralyx-Read-Only`	`true`	Only the tools that read are listed and allowed.

X-MCP-Toolsets and X-MCP-Readonly are read the same way.

What it may do#

Access	The assistant may
Read only	See your workspaces, machines and GPUs, runs and their logs and metrics, models and deployments, environments and notebooks, agents, drives, flows, usage. Nothing changes.
Read and write	Also start and change work: submit runs, add models from the catalog, deploy and scale them, call a deployment, create and start environments, run agents.
Read, write and admin actions	Also stop and remove work: cancel runs, stop environments, delete deployments.

Each level includes the one before. When a tool needs more than the connection has, Claude asks you to allow it (the others say so); you can also change it any time in Settings → Connected apps.

Confirmations#

Some actions are never done when the assistant asks: cancelling a run, stopping an environment, deleting a deployment — and, because they take GPUs, deploying a model and starting a flow or a schedule. The tool answers with a link; the console also shows it in your notifications.

Open the link (https://console.astralyx.cloud/confirm/act_…). The page says exactly what will happen, where, and which app asked.
Choose Approve and do it — it is done then, as you — or Deny.
The assistant checks the outcome with get_status.

A request not decided within 15 minutes expires. Only you, signed in to the console, can approve: never a token, so the assistant cannot approve its own request.

Toolsets and tools#

Toolset	On by default	Tools
`context`	always	`whoami`, `list_workspaces`, `set_default_workspace`, `get_status`
`machines`	yes	`list_machines`, `get_machine`
`runs`	yes	`list_runs`, `get_run`, `get_run_logs`, `get_run_metrics`, `list_run_templates`, `submit_run`, `cancel_run`
`eos`	yes	`list_models`, `search_model_catalog`, `add_model`, `list_deployments`, `get_deployment`, `create_deployment`, `scale_deployment`, `delete_deployment`, `call_deployment`
`hesperus`	yes	`list_environments`, `get_environment`, `create_environment`, `start_environment`, `stop_environment`, `list_notebooks`
`anemoi`	yes	`list_agents`, `run_agent`, `list_agent_runs`, `get_agent_run`, `get_agent_run_activity`
`data`	no	`list_drives`, `list_data_sources`
`flows`	no	`list_flows`, `trigger_flow`, `list_schedules`, `trigger_schedule`
`usage`	no	`get_usage`, `list_alerts`

Tool	Needs	What it does
`whoami`	read	You, and what this connection may do.
`list_workspaces`	read	Your workspaces (`<org>/<workspace>`), your role, their clusters; what was shared with you as a guest.
`set_default_workspace`	read	The workspace tools use when a call names none (this connection's preference).
`get_status`	read	The state of anything a tool started, by its handle; waits up to 60 s for it to settle.
`list_machines`	read	Machines the workspace may use: state, GPUs (model, how many, how many free), pool, health.
`get_machine`	read	One machine: why it is down or degraded and what to check, each GPU's health and faults, what runs on it.
`list_runs`	read	Runs, newest first, by state or name.
`get_run`	read	One run; when it waits, why — each machine looked at and what it lacked.
`get_run_logs`	read	The end of a worker's log (up to 2 000 lines).
`get_run_metrics`	read	GPU and CPU use and memory per worker, now and over the last hour.
`list_run_templates`	read	The workspace's run templates.
`submit_run`	write	Start a run from a template, or an image and a command, with GPUs.
`cancel_run`	admin actions	Cancel a run, after your confirmation.
`list_models`	read	The workspace's models.
`search_model_catalog`	read	Open models Astralyx can deploy, with the GPU memory each needs.
`add_model`	write	Bring a catalog model into the workspace.
`list_deployments`, `get_deployment`	read	Deployments: state, replicas, how to call them; recent traffic and speed.
`create_deployment`	write	Deploy a model, after your confirmation.
`scale_deployment`	write	Replicas: a number, a range by load, or 0 to scale to zero when idle.
`delete_deployment`	admin actions	Delete a deployment (the model stays), after your confirmation.
`call_deployment`	write	One chat message to a deployment, its answer back (up to 1 024 tokens, one minute).
`list_environments`, `get_environment`	read	Environments, and how to connect: `astra ssh`, the IDE.
`create_environment`, `start_environment`	write	Create one (with GPUs if asked) or start one again.
`stop_environment`	admin actions	Stop one (files kept), after your confirmation.
`list_notebooks`	read	The workspace's notebooks.
`list_agents`, `list_agent_runs`, `get_agent_run`, `get_agent_run_activity`	read	Agents, their runs, a run's output and trace, and everything it reached outside its sandbox.
`run_agent`	write	Start an agent run.
`list_drives`, `list_data_sources`	read	Drives and data sources, with details for one.
`list_flows`, `list_schedules`	read	Flows and schedules.
`trigger_flow`, `trigger_schedule`	write	Start one now, after your confirmation.
`get_usage`	read	An organisation's GPU hours, tokens and cost, per workspace.
`list_alerts`	read	An organisation's alert rules and what fired recently (its owners and admins).

Tools that list take limit and answer next_cursor for the next page; those that describe take detail: true for every field. Long operations — a run, a deployment, an environment, a flow — answer at once with a handle; get_status follows it.

Limits and security#

As you, nothing more. Every call is checked as a request of yours in the console: your role in the workspace, the machines its pools give it. A guest reaches only the environment or notebook shared with them.
Tokens are for the MCP server only. The assistant's tokens are refused by the console and the API. They last an hour and are renewed while you use the assistant; a connection unused for 30 days must connect again. A renewal token used twice ends the connection.
Disconnect any time in Settings → Connected apps, or narrow what it may do; the next call follows. Your data export lists your connected apps.
What programs wrote is data. Logs, an agent's output and a model's answers come back marked as data written by programs. A cautious assistant does not follow instructions found in them; confirmations stop the costly or destructive ones regardless.
30 requests a minute per connection, in bursts of up to 30 (429 with Retry-After beyond). Each answer is at most 24 KiB of text.
Requests from web pages other than the console are refused.
Protocol: MCP streamable HTTP, version 2026-07-28; 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 clients are served too. For client developers: protected resource metadata at https://console.astralyx.cloud/.well-known/oauth-protected-resource/mcp, authorization server metadata at https://console.astralyx.cloud/.well-known/oauth-authorization-server (Client ID Metadata Documents, dynamic registration, PKCE S256, iss in responses).

Troubleshooting#

Symptom	Cause	Fix
The client cannot reach or authorize the server	The URL is not exactly `https://console.astralyx.cloud/mcp`	Remove the server and add it again with that URL.
This request is no longer open in the console	The sign-in took more than 15 minutes, or the page was answered already	Connect again from the assistant.
A tool says its toolset is turned off	The connection's toolsets leave it out	Settings → Connected apps → its tools.
A tool needs a permission the connection was not given	It needs write or admin actions	Allow it when the assistant asks, or change it in Connected apps.
pass `workspace`	You have several workspaces and none is the default	Name it (`<org>/<workspace>`), or have the assistant call `set_default_workspace`.
not allowed (RBAC_FORBIDDEN)	Your role there does not allow it (a viewer submits nothing)	Ask a workspace admin.
A confirmation link says it expired	Not decided within 15 minutes	Ask the assistant again.