Turbine MCP

Quickstart

Copy and paste this to your agent:

Install the turbinefi MCP using these docs: https://www.turbinefi.com/docs/mcp

Turbine MCP lets a compatible AI client work with your Turbine Studio account. The AI can inspect your strategies, trading logs, live status, research, and backtests; ask Turbine's account-aware AI for context; and help you make supported changes.

Use this remote MCP server URL:

https://api.turbinefi.com/api/v1/mcp

You do not need to create or copy an API key. Turbine MCP uses OAuth, so authentication happens on turbinefi.com and your Turbine password or login code never passes through the AI client.

Connect your AI client

Your client must support remote Streamable HTTP MCP servers and either browser-redirect OAuth or OAuth device authorization.

1. Open your AI client's MCP or integrations settings.
2. Add a remote MCP server using https://api.turbinefi.com/api/v1/mcp.
3. When your browser opens Turbine, sign in with the same method you normally use on turbinefi.com.
4. Review the client name, origin, and requested access on the Accept connection page.
5. Select Accept connection. Return to the AI client when Turbine tells you the connection is approved. The client can then discover the available tools.

Any registered Turbine account can connect. The connection receives the full MCP tool catalog, while every request still follows the account's current membership limits, ownership rules, and usage limits.

Only approve a connection when you recognize the client name and origin. A connected client can read your Turbine account and request supported account changes.

Local AI clients

Local applications such as desktop clients and CLIs use OAuth 2.1 authorization code flow with PKCE. The client starts a temporary callback listener on 127.0.0.1 (localhost), opens the Turbine Accept connection page in your browser, and receives the authorization result through that local callback after you approve it.

The localhost callback works because the browser and the OAuth client run on the same computer. Keep the client running until the browser returns to it.

Server-side agents

Server-side agents such as Meta's Muse run on a remote VM, so a loopback browser callback cannot reach them. Use the OAuth 2.0 Device Authorization Grant (RFC 8628) instead.

Endpoints

Hosted / remote AI clients

1. Register a confidential client with DCR and save the returned client_id and client_secret.
2. Request a device code with HTTP Basic authentication and resource=https://api.turbinefi.com/api/v1/mcp.
3. Show the user both verification_uri_complete and user_code. The complete URL pre-fills the code; the user signs in, reviews the client, and approves it.
4. Poll the token endpoint no faster than the returned interval, again using HTTP Basic authentication and the same resource. Continue after authorization_pending; after slow_down, add five seconds to the polling interval. Stop on access_denied, expired_token, or invalid_grant.

Device and user codes expire after ten minutes. A successful device-code exchange consumes the code, so a later request returns invalid_grant.

The following example requires curl and jq. Run it in Bash, then approve the displayed URL in your browser:

set -euo pipefail

API=https://api.turbinefi.com
RESOURCE=https://api.turbinefi.com/api/v1/mcp

registration="$(curl --fail-with-body --silent --show-error \
  --request POST "$API/oauth/register" \
  --header 'Content-Type: application/json' \
  --data '{"client_name":"My server-side agent","client_uri":"https://agent.example.com","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"],"token_endpoint_auth_method":"client_secret_basic","scope":"mcp:tools"}')"
CLIENT_ID="$(printf '%s' "$registration" | jq -er '.client_id')"
CLIENT_SECRET="$(printf '%s' "$registration" | jq -er '.client_secret')"

authorization="$(curl --fail-with-body --silent --show-error \
  --request POST "$API/oauth/device/authorize" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "resource=$RESOURCE" \
  --data-urlencode 'scope=mcp:tools')"
DEVICE_CODE="$(printf '%s' "$authorization" | jq -er '.device_code')"
interval="$(printf '%s' "$authorization" | jq -er '.interval')"
printf 'Open %s\nUser code: %s\n' \
  "$(printf '%s' "$authorization" | jq -r '.verification_uri_complete')" \
  "$(printf '%s' "$authorization" | jq -r '.user_code')"

while :; do
  sleep "$interval"
  body_file="$(mktemp)"
  curl_exit=0
  http_code="$(curl --silent --show-error \
    --request POST "$API/oauth/token" \
    --user "$CLIENT_ID:$CLIENT_SECRET" \
    --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    --data-urlencode "device_code=$DEVICE_CODE" \
    --data-urlencode "resource=$RESOURCE" \
    --output "$body_file" --write-out '%{http_code}')" || curl_exit=$?

  if token="$(jq -cer 'select(.access_token and .refresh_token)' "$body_file" 2>/dev/null)"; then
    rm -f "$body_file"
    printf '%s\n' "$token"
    break
  fi

  error="$(jq -r '.error // empty' "$body_file" 2>/dev/null || true)"
  case "$error" in
    authorization_pending) rm -f "$body_file" ;;
    slow_down) interval=$((interval + 5)); rm -f "$body_file" ;;
    access_denied|expired_token|invalid_grant)
      printf 'Device flow stopped: %s\n' "$error" >&2
      rm -f "$body_file"
      exit 1
      ;;
    *)
      if [ "$http_code" = 200 ]; then
        printf 'Ambiguous HTTP 200; inspect %s before a new device flow. Do not retry this device code.\n' "$body_file" >&2
        exit 1
      fi
      rm -f "$body_file"
      if [ "$curl_exit" -ne 0 ] || [ "$http_code" = 429 ] || [[ "$http_code" == 5?? ]]; then
        interval=$((interval * 2))
      else
        printf 'Token request failed with HTTP %s.\n' "$http_code" >&2
        exit 1
      fi
      ;;
  esac
done

The access token expires after 900 seconds. Refresh tokens expire after 30 days and rotate on every refresh: store the new refresh token and discard the old one. Reusing an old refresh token revokes its entire token family and OAuth grant. Each rotated refresh token receives a new 30-day lifetime.

Connection failures during token polling

api.turbinefi.com can intermittently drop a connection mid-response. Retry connection failures, HTTP 429, and HTTP 5xx responses with backoff. When polling returns HTTP 200 but the connection fails, inspect and parse the saved body first; it may contain the issued token even if the HTTP client reported an error.

Never blindly retry the same device code after an ambiguous HTTP 200. The server may have consumed the single-use code and committed the tokens before the connection dropped; a retry then returns terminal invalid_grant. If the saved body does not contain a complete token response, stop and begin a new device flow.

What the AI can do

Turbine MCP exposes owner-scoped tools for the same Studio workflow you use on the website.

Results are scoped to the authenticated account. Connecting MCP does not give one user access to another user's strategies, runners, logs, or credentials.

Finding account resources

To browse the published library at /studio/strategies, use list_strategy_library. Set sort to recent for newest first, or to name, pnl, roi, sharpe, win_rate, stars, or market; use order for ascending or descending results. Search with query, and filter by platform, category, asset, interval, engine, or market. Set group to family to discover strategy families, then pass a returned family_key as family to compare its variants. Follow next_cursor with the same filters and sorting to continue the list. get_library_strategy accepts an entry's ID or slug as strategy_id and returns its rules, parameters, and available backtest details. Library IDs can also be used with copy_shared_strategy.

To browse the published Deep Research collection at /studio/research, use list_public_research_reports. It returns completed reports newest completed first, with next_cursor for older results. Pass a returned slug to get_public_research_report to read the analysis and strategy comparisons. These public library tools are separate from your owned strategy and research tools below.

Start with list_strategies to find your saved Studio strategies. Pass query to search their names, titles, and strategy labels. Search returns the newest matching results up to the requested limit and sets truncated when more exist. Without query, use next_cursor to page through strategies. The returned id is the strategy_id for get_strategy; current Studio deployments also use that session ID as bot_id for deployment and analytics reads. Use list_sessions when you need the Studio conversation history; it also supports next_cursor.

Use list_journal_runs to find recent live and paper runs, then pass run_id to the journal detail, event, contract, and sample tools. Use list_research_reports to find a report_id for get_research_report. Research list entries are compact summaries; follow next_cursor for older reports.

ask_turbine receives a bounded snapshot of the account's recent sessions, journal runs, and research reports alongside any resource IDs you supply. For a question about older activity or a specific strategy, first find its ID with the list tools and pass that ID to ask_turbine. A nonempty next_cursor means the snapshot is incomplete; continue paging before making an account-wide claim.

For preview_action, create_strategy needs platform and message. update_strategy needs session_id and message; start_backtest needs session_id; research actions need a report_id or the draft fields appropriate to that action. A preview does not execute anything. Use its confirmation token only after the user approves that exact preview.

Flexible requests

You can ask an agent to browse newly published strategies, explain a research report, inspect one running bot, compare parameter variants, create a draft, or inspect deployment activity. Combine these capabilities in a natural-language request when useful. MCP supplies a capability guide at connection time so the agent can choose the tools relevant to your request; there is no required sequence of strategy creation and backtesting for every task.

For a request to improve parameters, the agent should compare proposed changes with the current baseline and explain the available evidence. Deployment changes are unavailable through MCP, including changes to paper deployments. Existing deployment previews and confirmation tokens cannot execute deployment actions. Recurring notifications require a schedule configured in the AI client.

Preview and confirm changes

Reading data does not require confirmation. Consequential changes use the same two-step safety model as the Turbine interface:

1. The AI calls preview_action with the proposed action and exact parameters.
2. Turbine validates the request and returns a human-readable summary, warnings, affected resource versions, and a short-lived confirmation token. Nothing changes yet.
3. The AI shows you that preview and asks for explicit confirmation.
4. Only after you confirm may the AI call confirm_action with the one-time token.

Confirmation tokens expire after five minutes and work only for the connection that created them. Consumed confirmations cannot be reused. Deployment confirmation tokens issued before deployment controls were disabled are also rejected. If the protected resource changes between preview and confirmation, Turbine rejects the confirmation and requires a fresh preview. Low-risk session renames are immediate and idempotent; they do not change trading state.

Deployment controls

MCP supports strategy drafts, backtests, research, and reads of existing deployment activity. It does not support deploy, update, switch, stop, recover, redeploy, or cancel-deployment actions, in either live or paper mode. These actions are absent from the advertised action schema and rejected by the server, including confirmations issued before deployment controls were disabled.

Manage deployments directly in Turbine Studio. Editing a saved draft through MCP does not send an update to a running bot. Runner credentials never pass through MCP.

Membership and plan limits

MCP does not bypass Turbine membership rules. Bot caps, feature availability, rate limits, and other account limits are checked against the current plan when a tool runs. If a tool requires a different plan, the response includes a plan_limit_reached error and a direct link to Membership.

Changing plans does not require reconnecting the AI client. The next tool call uses the updated account limits.

Tasks that stay on turbinefi.com

For security and direct user control, MCP does not accept payment details, venue credentials, deposits, or withdrawal instructions. Configure venue credentials and manage deployments directly on turbinefi.com. Do not paste API keys, private keys, seed phrases, passwords, or other secrets into an MCP conversation.

When one of these prerequisites blocks an operation, the MCP response includes a stable error such as credentials_required or plan_limit_reached, plus the exact steps, destination URL, and tool to retry afterward. The AI should explain those steps but cannot complete the website-only action for you.

Reconnecting an AI client does not enable deployment controls. Deployment actions remain unavailable through MCP.

Manage connected clients

Open Membership and find AI connections to review each connected client's name, origin, connection date, and last-use time.

Select Revoke to disconnect a client. Revocation takes effect immediately: existing access and refresh tokens stop working, and the client must complete the browser authorization flow again before it can access Turbine.

Troubleshooting

The browser does not open

Confirm that the AI client supports OAuth for remote MCP servers, then remove the incomplete connection and add the Turbine MCP URL again.

The connection request expired

Return to the AI client and start a new connection. Authorization requests are short-lived and cannot be reopened after they expire.

A tool says setup is required

Follow the steps and URL returned in the error. Complete the membership, runner, funding, or credential task on turbinefi.com, then ask the AI to retry the named tool.

A confirmation failed

Ask the AI for a new preview. The earlier token may have expired, already been used, or become invalid because the strategy or deployment changed after the preview.

A previously connected client receives an authentication error

Check AI connections on the Membership page. If the connection was revoked, reconnect from the AI client and approve the new browser request.