Astral MCP

Astral’s remote Model Context Protocol endpoint lets a compatible AI client connect to Astral after you authorize access. The public setup page is available at Astral MCP.

Start from Astral

Choose Connect AI client in Terminal's left rail, Settings → AI connections, or Open menu → AI Connections on mobile. The mobile flow opens a sheet with the same surface and grabber styling as Positions; client selection and setup steps remain below. Select ChatGPT, Codex, Claude, Claude Code, Gemini, Grok Bot, Cursor or Other to see the setup instructions, installer or copyable command for that client.

The setup cards load the connection URL configured for that Astral site's environment and product. The displayed URL, copied commands and Cursor installer use the same resource. Wait for setup to load before copying. If the URL is unavailable, choose Retry connection setup or contact support; do not substitute a production URL, another product's URL or an assumed legacy alias.

Endpoint

This is a production example, not a universal Dev or product URL:

https://stream.astral-prod.heyastral.ai/api/mcp

Use a streamable HTTP or remote MCP server configuration named astral. The client should open Astral’s sign-in and consent flow when authorization is required.

For authorized dev testing, open the intended Dev product first, then copy its current URL from Settings → AI connections, Connect AI client, or the site's MCP setup page. Use the name Astral Dev and sign in with the matching Dev identity. Do not change an in-progress authorization URL to make two different hosts appear equivalent.

Production, Dev and separate products can use different resources. Keep the exact resource path and matching identity. The full /api/mcp and restricted /api/mcp/openai profiles are not interchangeable; reconnect with the intended profile rather than removing /openai to bypass a refusal. MCP is not an OpenAI API key or a Custom GPT Action; normal setup uses remote OAuth without a manually supplied client ID/secret. Workspace Paper/Real money does not select another MCP product or environment, and connection setup changes neither mode nor financial permissions. Mobile web uses the same configured URL; native-client support still depends on that client's remote OAuth implementation.

Onchain Dev also retains one explicit compatibility entry: https://stream.astral-dev.heyastral.ai/api/mcp and its restricted /openai profile. An authorization started there keeps that exact resource throughout consent, code exchange and use; it is not rewritten to the newer Onchain address or accepted by Classic. New connections should still copy the current Onchain setup URL. This exception does not authorize other old hosts, production aliases or broader profiles.

Connect ChatGPT

1. Open the ChatGPT setup card in Astral and follow its Developer mode link. Client labels and access depend on your ChatGPT account/workspace.
2. Enable Developer mode where permitted, then open the custom apps/plugins connection screen and choose its add/create control.
3. Enter Astral (or Astral Dev) and the matching full endpoint as a public remote connection.
4. Create the connection, inspect the discovered tools, and complete Astral sign-in/consent when prompted.
5. Start a conversation and enable the Astral app/plugin in its tools menu. Ask “Use Astral to show my account status” to check the connected identity.

If Developer mode or custom connections are unavailable, check the client's plan and organization policy. See OpenAI's setup instructions for its current screen names.

Connect Claude

1. Open Customize → Connectors, or Settings → Connectors in clients that use that navigation.
2. Choose + → Add custom connector, enter Astral or Astral Dev and the corresponding endpoint.
3. Leave optional OAuth Client ID/Secret fields empty unless Astral support supplied special values.
4. Choose Add, then Connect, and complete the matching Astral sign-in and consent flow.
5. In a Claude conversation, enable Astral from the + → Connectors menu.

Team/Enterprise organizations can require an owner to add the connector under organization settings before members authorize their own accounts. See the Claude connector guide for current client requirements.

Client setup

1. Add the remote server

   Use the client-specific installer or add the endpoint to the client’s MCP configuration. The MCP setup page provides current instructions for ChatGPT, Claude, Cursor, Codex, Gemini, and generic compatible clients.

2. Sign in to Astral

   Complete the browser sign-in flow with the Astral account whose data and entitlements you intend to use.

3. Review and approve consent

   Read the requested access before approving it. Decline or close the flow if the client or requested connection is unfamiliar.

4. Confirm the connection in your client

   Return to the client and check its server or tools status. Tool availability can depend on your Astral account, current rollout, and the client’s MCP implementation.

Command examples

Choose your client in the current site's setup card to copy its matching command or configuration. The static commands below are production examples only; they are not Dev installers.

Security and troubleshooting

• Only authorize clients you trust.
• Treat actions involving strategies, alerts, or trading as consequential and review them in Astral.
• If authorization stalls, remove the server from the client, add it again, and complete sign-in in the newly opened browser flow.
• If consent says The requested MCP resource does not match this Astral site, stop that flow. Open View connection setup for this site, confirm that it is the environment/product you intended, then restart the connection from your MCP client with its matching URL and original profile. If this is the wrong site, return to the intended product rather than switching accounts to bypass the error. An old host advertising discovery does not establish that it is an authorized alias. Report conflicting discovery/consent URLs to support; do not edit the authorization request, disable resource checks or retry with a broader profile.
• If the server connects but a capability is unavailable, check your Astral plan, feature access, and the client’s support for remote OAuth MCP servers.
• Disconnect the integration from the client if a device or configuration is no longer trusted.

What the connection means

MCP is a protocol connection between a compatible client and Astral’s remote server. It does not copy your entire Astral account into the client. The available tools and data remain subject to the authorized account, Astral feature access, server rollout, and the client’s implementation.

Adding the server configuration identifies the endpoint. Signing in identifies the Astral account. Approving consent authorizes the requested connection. These are distinct steps, and removing only the text configuration may not be equivalent to revoking an existing authorization in every client.

Use MCP safely

• Verify the endpoint exactly before authorizing.
• Read the client’s tool confirmation and Astral consent screens.
• Use an Astral account appropriate for the work context.
• Review consequential output in Astral, especially strategies, alerts, orders, or account-related state.
• Remove or revoke connections on lost, shared, or untrusted devices.
• Never paste an Astral password or one-time code into an ordinary chat message.

An AI client can misunderstand a request or choose the wrong available tool. Phrase instructions with the same specificity you would use in Terminal: symbol, interval, dates, intended record, and whether the request is research-only.

Preview an order before submitting

astral_order_preview checks an order without submitting it, and a preview is not a fill. For a buy on an Astral Paper account (simulated cash), the preview also compares the order's estimated cost with the account's available Paper cash, meaning cash not allocated to strategies or held by open orders. It reports Buying power (the cost and, when short, the cash available) and a funding result of ready, insufficient or unknown.

When funding is insufficient, the preview is not accepted, Order size shows as invalid and the warning states the shortfall. Reduce the size or add Paper cash, then preview again. A market order's cost is estimated from the latest price and can differ when the order runs; a limit order uses its limit price. If the account's cash or a current price cannot be read, funding is unknown and the warning says Cash was not checked; the preview does not claim the order is affordable.

This check covers Astral Paper buys only. Sells, Astral Wallet and perps previews, and linked real brokerage accounts keep their own checks. Review the order in Astral before submitting.

Multiple clients and accounts

Each client can store server configuration and authorization differently. If you use more than one client, do not assume disconnecting one removes the others. Confirm which Astral account completed each consent flow.

When switching accounts, remove the existing server authorization or sign out through the client’s supported flow before reconnecting. A stale authorization can make an account mismatch look like missing product data.

If you combined two sign-in methods into one account (see One account for each email), a client connected with the other method stops working. Reconnect it once; it then opens the combined account.

Diagnose a connection

Recover a strategy calculation error

When a connected AI client builds a strategy with paired entries and exits (trade_rules), calculations that need price history—such as EMA, RSI and crossovers—belong in the top-level series array of astral_strategy_build. An older error may call this derived_series; that is an internal/source-language name, not an accepted MCP request field. Adding it at the top level or inside a trade rule will be rejected.

Ask the client to declare each calculation with alias and expr, then reference the alias in the entry or exit condition. For example, for a declared asset named BTCUSD, these are the calculation declarations (a fragment of the build request):

{
  "series": [
    {"alias": "FAST", "expr": "EMA(BTCUSD.close, 48)"},
    {"alias": "SLOW", "expr": "EMA(BTCUSD.close, 160)"}
  ]
}

The entry condition can then be candidate.FAST > candidate.SLOW, and the exit condition position.FAST < position.SLOW. For a ranked dynamic asset named picks, use picks.close in the declarations instead. candidate is the current entry candidate; position follows the token that trade actually holds, even after it leaves the screen. Keep the requested assets, calculations and entry/exit meaning when correcting the request; these examples are not replacement trading rules.

Two mistakes produce most of these errors:

• candidate or position inside a series. Those words exist only in entry and exit conditions. Inside expr, name the asset itself: BTCUSD.close, not candidate.close.
• A bare alias in a condition. Write candidate.FAST (entry) or position.FAST (exit), not FAST.

A series can build on an earlier series of the same asset. For example, a Supertrend-style line and its crossover on BTCUSD:

{
  "series": [
    {"alias": "ST", "expr": "(BTCUSD.high + BTCUSD.low) / 2 - 2.5 * ATR(BTCUSD.high, BTCUSD.low, BTCUSD.close, 10)"},
    {"alias": "XA", "expr": "CROSS_ABOVE(BTCUSD.close, ST)"},
    {"alias": "XB", "expr": "CROSS_BELOW(BTCUSD.close, ST)"}
  ]
}

with entry candidate.XA and exit position.XB. The error message names the series or condition to change and shows the form to use.

Use validate_only=true to check the corrected complete build without creating or replacing a strategy. Successful validation is not a backtest or deployment. Ordinary rules use their separate condition field; they are not a replacement for independently managed trade entries and exits. This request format applies to compatible remote clients on desktop and mobile; client tool availability still depends on the connected profile and rollout, and changing Paper/Real money does not repair an invalid request.

Recover a lost strategy or backtest response

After an uncertain build response, use astral_strategy_list with a name query and follow next_cursor until has_more=false. Each page has at most 50 records in the authorized workspace. Verify the matching source with astral_strategy_get before rebuilding.

Use a client request_key for backtest admission whenever possible. If an earlier call omitted one, astral_strategy_get includes up to 20 recent admission jobs, including pending/running IDs; poll the matching ID with astral_backtest_status rather than starting another run. backtest_jobs_has_more indicates older jobs were omitted. A previous completed result does not establish that no new job was admitted.

astral_account_status.backtest_capacity reports the user limit, occupied slots and available slots when the distributed capacity store is reachable. This is shared across sessions, and availability is not guaranteed until admission. Date-only backtest end overrides include the whole UTC day; explicit timestamps retain their exact meaning.

Inspect wallet order history

Read wallet orders through MCP

1. Identify the intended wallet account or strategy and the token's exact network/address. Do not substitute a same-ticker token or another account's history.
2. Use astral_order_list with that account_id or strategy_id to inspect its recorded orders.
3. Use astral_order_get with the returned order's intent_id to read its recorded status, requested spend or token quantity, and available settled amounts. A requested amount and a settled amount are different facts.

Protective exits can appear under their entry when both are in the returned list. Reading wallet order history through MCP neither submits a trade nor changes protection. An empty history or reader error is not a reason to submit a replacement trade; check the intended account, network and order record first.

Does a requested USDG spend mean the Robinhood Chain buy filled?

No. The requested amount is not proof of a fill. A summary such as spend 1 USDG describes what the Robinhood Chain order requested, not a confirmed purchase. Inspect its recorded status and settled amounts; an uncertain or pending outcome must not be presented as a completed buy. A missing chart arrow is not proof that the purchase failed either.

EVM market orders use their recorded normalized input amount, including when the original request used a decimal amount. Amounts stay in the execution network's currency: USDC on Base/Arbitrum, USDG on Robinhood Chain, not a converted global USD balance. Check the exact token address and account before taking any separate action. These are read-only history instructions for compatible MCP clients, not a new execution authorization or a guarantee that a client can render chart markers.

Reporting an MCP issue

Include the client name and version, operating system, endpoint, stage that failed, approximate time, and non-sensitive error text. Do not include access tokens, authorization codes, passwords, or complete request headers.

astral_report_bug can add context to your own open automatic report, including one created by a REST backtest. report_reference_unavailable means the supplied reference is invalid, closed or unavailable to your account; it does not mean report storage is down. Check the report reference rather than automatically duplicating it. reporting_unavailable describes a persistence failure; preserve the details for retry.

Token search may return identities with partial metadata and a diagnostic_id. Include that ID when reporting a timeout. result_position and ranking.rank number the returned page; provider_rank preserves an upstream rank separately. Never use rank alone to select a token with an ambiguous ticker.