BotSpot: AI Trading, Backtests and Bots

Update saved broker credential

update_broker_credential

DestructiveIdempotent

Updates broker credential metadata and optionally replaces Vault material for the authenticated owner. This replaces the saved credential values when credentialValues is provided; it never returns raw values. For a broker or exchange API key used to trade, tell the user to enable trading. Before setup or replacement, give this warning only when the broker offers those permissions separately: Warning. Only turn on trading permissions. Leave deposits and withdrawals off. Use the broker’s actual settings. If a broker bundles transfers with trading, explain that when relevant and keep trading available. Never ask the user to paste credentials into chat. For interactive setup or replacement, send the user to BotSpot Broker Connections (/account-settings/broker-connections) to enter the key there. Use this for broker login/trading credentials only. Do not add a brokerCredentialId to a deployment by default; let the user choose on the approval page unless they explicitly named the exact saved broker connection/account. The broker field controls validation for known Lumibot/BotSpot brokers; use the exact environment variable key names below. Kalshi (kalshi): KALSHI_API_KEY_ID + KALSHI_PRIVATE_KEY. Optional: KALSHI_SUBACCOUNT, KALSHI_EXCHANGE_INDEX, KALSHI_BASE_URL, KALSHI_WS_URL. Do not pass KALSHI_IS_DEMO; BotSpot derives it from paperOrLive. Example credentialValues: {"KALSHI_API_KEY_ID":"key-id...","KALSHI_PRIVATE_KEY":"private-key-pem..."}. Alpaca (alpaca): ALPACA_API_KEY + ALPACA_API_SECRET OR ALPACA_OAUTH_TOKEN. Do not pass ALPACA_IS_PAPER; BotSpot derives it from paperOrLive. Example credentialValues: {"ALPACA_API_KEY":"PK...","ALPACA_API_SECRET":"secret..."}. Tradier (tradier): TRADIER_ACCOUNT_NUMBER + TRADIER_ACCESS_TOKEN OR TRADIER_ACCOUNT_NUMBER + TRADIER_API_KEY OR TRADIER_ACCOUNT_NUMBER + TRADIER_TOKEN. Optional: TRADIER_REFRESH_TOKEN, TRADIER_OAUTH_CLIENT_ID, TRADIER_OAUTH_CLIENT_SECRET. Do not pass TRADIER_IS_PAPER; BotSpot derives it from paperOrLive. Example credentialValues: {"TRADIER_ACCOUNT_NUMBER":"6AB12345","TRADIER_ACCESS_TOKEN":"token..."}. Charles Schwab (schwab): SCHWAB_ACCOUNT_NUMBER + SCHWAB_TOKEN. Example credentialValues: {"SCHWAB_ACCOUNT_NUMBER":"123456789","SCHWAB_TOKEN":"base64url-token-payload..."}. Tradovate (tradovate): TRADOVATE_USERNAME + TRADOVATE_DEDICATED_PASSWORD + TRADOVATE_CID + TRADOVATE_SECRET. Optional: TRADOVATE_APP_ID, TRADOVATE_APP_VERSION. Do not pass TRADOVATE_IS_PAPER; BotSpot derives it from paperOrLive. Example credentialValues: {"TRADOVATE_USERNAME":"username...","TRADOVATE_DEDICATED_PASSWORD":"dedicated-password...","TRADOVATE_CID":"client-id...","TRADOVATE_SECRET":"secret..."}. TopstepX (projectx-topstepx): PROJECTX_TOPSTEPX_API_KEY + PROJECTX_TOPSTEPX_USERNAME. Optional: PROJECTX_TOPSTEPX_PREFERRED_ACCOUNT_NAME. Example credentialValues: {"PROJECTX_TOPSTEPX_API_KEY":"key...","PROJECTX_TOPSTEPX_USERNAME":"username..."}. WEEX (weex): WEEX_API_KEY + WEEX_API_SECRET + WEEX_API_PASSPHRASE. Example credentialValues: {"WEEX_API_KEY":"key...","WEEX_API_SECRET":"secret...","WEEX_API_PASSPHRASE":"passphrase..."}. Bitunix (bitunix): BITUNIX_API_KEY + BITUNIX_API_SECRET. Optional: BITUNIX_TRADING_MODE. Example credentialValues: {"BITUNIX_API_KEY":"key...","BITUNIX_API_SECRET":"secret..."}. Kraken (kraken): KRAKEN_API_KEY + KRAKEN_API_SECRET. Example credentialValues: {"KRAKEN_API_KEY":"key...","KRAKEN_API_SECRET":"secret..."}. Coinbase (coinbase): COINBASE_API_KEY_NAME + COINBASE_PRIVATE_KEY. Optional: COINBASE_API_PASSPHRASE, COINBASE_SANDBOX. Example credentialValues: {"COINBASE_API_KEY_NAME":"organizations/.../apiKeys/...","COINBASE_PRIVATE_KEY":"-----BEGIN EC PRIVATE KEY-----..."}. Any other CCXT 4.5.64 exchange id (for example okx, binance, bybit, bitget, hyperliquid): use that id as the broker and the credentials it requires, named _API_KEY, _API_SECRET, _API_PASSPHRASE, _UID, _PRIVATE_KEY or _WALLET_ADDRESS. Do not pass _SANDBOX; BotSpot derives it from paperOrLive. Do not put data-provider API keys, screener rows, CSV data, workbooks, JSON dumps, or BotSpot internal keys here; use saved_env_vars(action="create") for non-broker runtime secrets.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "update_broker_credential"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes
`broker`	No
`displayName`	No
`paperOrLive`	No
`credentialValues`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, and the description adds real value on top: it discloses that saved values are replaced when credentialValues is supplied, that raw values are never returned, that scope is the authenticated owner, and that the broker field drives validation. It does not cover error behavior or what happens to metadata fields omitted from a call, which keeps it short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose statement and replacement semantics are front-loaded in the first two sentences, which is good. But the body is an extremely long per-broker key dump with repeated 'Do not pass ..._IS_PAPER; BotSpot derives it from paperOrLive' phrasing, and the trading-permission warning paragraph is verbose and hedged ('give this warning only when ...', 'explain that when relevant'), so a meaningful share of text is redundant or hard to act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, open-world mutation with a free-form nested object and no output schema, this is substantially complete: credential formats, no-raw-value guarantee, owner scoping, and an out-of-band UI path are all covered. Remaining gaps are minor but real — no statement about partial versus full replacement of metadata, no failure-mode guidance, and no explanation of id or displayName semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it discharges that burden well for the hardest parameter: the nested credentialValues object gets per-broker required key names, optional keys, exclusions (e.g. do not pass KALSHI_IS_DEMO, ALPACA_IS_PAPER), and concrete JSON examples across ten-plus brokers plus a generic CCXT fallback. It is silent on id and displayName, and explains paperOrLive only indirectly via the IS_PAPER/IS_DEMO derivation note, so two parameters remain undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Updates broker credential metadata and optionally replaces Vault material for the authenticated owner') and scopes it explicitly ('Use this for broker login/trading credentials only'). It also names the sibling it is not by routing non-broker secrets to saved_env_vars(action="create"), so an agent can distinguish it without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when/when-not guidance: replace Vault material only when credentialValues is provided, send the user to BotSpot Broker Connections for interactive setup or replacement, never ask the user to paste credentials into chat, and do not attach a brokerCredentialId to a deployment by default. It also names a concrete alternative for out-of-scope secrets (saved_env_vars) and conditions the permission warning on whether the broker offers permissions separately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All BotSpot: AI Trading, Backtests and Bots tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.