# How do I set up the Webull MCP without trading live by accident?

Webull's Local MCP docs state that the default environment is uat, which they call sandbox. Every copy-paste client config on the same page sets prod. If you paste the example as written, you are on production.

Checked on 2026-10-17.

No business relationship with Webull.

How the uat sandbox fits the staged ladder is on the [paper trading guide](/guides/ai-agent-paper-trading).

Before your agent sends a Webull order, run it through the free [Agent Order Check](/check), and keep your limits in a file the agent does not write ([How do I stop an AI agent from placing a bad trade?](/guides/ai-agent-trading-guardrails)). Webull's own order caps are below. They are not a substitute for your own limits.

## Does the Webull MCP default to paper or live?

The Local MCP defaults WEBULL_ENVIRONMENT to uat, which Webull's docs call sandbox. The catch is the setup page. The Cursor, Claude Desktop and Kiro configs all set prod, and the sandbox switch sits in a tip below them. Paste the example as written and you are on production. Change that one line to uat first.

The configuration table on the [Local MCP page](https://developer.webull.com/apis/docs/AI-friendly-Resources/local-mcp) says `WEBULL_ENVIRONMENT` is `uat` (sandbox) or `prod` (production), and the default column is `uat`. The Cursor block edits `.cursor/mcp.json`. The Claude Desktop block edits `claude_desktop_config.json`. The Kiro block edits `.kiro/settings/mcp.json`. Each of those three sets `"WEBULL_ENVIRONMENT": "prod"`. Under them, the page says: for a sandbox environment, set `WEBULL_ENVIRONMENT` to `uat`.

The [project readme](https://github.com/webull-inc/webull-openapi-mcp) says the server defaults to UAT (sandbox), and that you must set `WEBULL_ENVIRONMENT=prod` for live trading. It labels the prod JSON as option A, "MCP client configuration (recommended for production)". The docs page shows that same prod JSON without the production label, and puts the sandbox switch in the tip.

The [broker connectors](/guides/broker-ai-connectors) page is the cross-broker list. Its Alpaca row says that MCP defaults to paper. The Webull examples quoted above set prod. The short Webull Cloud and Local rows live on that page. This page is the setup.

## How do I connect Webull to Claude Desktop?

Install uv, which gives you uvx. Webull's page requires Python 3.10 or newer. Put the stage 1 block below in claude_desktop_config.json, with a sandbox app key and WEBULL_ENVIRONMENT set to uat. If that account uses 2FA, run the auth command and approve it in the Webull app. Restart, then ask for your account list.

The [Local MCP page](https://developer.webull.com/apis/docs/AI-friendly-Resources/local-mcp) lists uvx, and Python 3.10 or newer, as the install requirement. It says the client downloads the server through uvx, so you do not install the package yourself. The same env block is what that page shows for `.cursor/mcp.json` and `.kiro/settings/mcp.json`. Change the environment line to uat in those files too.

Stage 1 is on uat, with the toolset the Local MCP page calls read-only. The values are strings because the env block is JSON. Replace the two key placeholders with a sandbox app key and app secret. Do not paste those values into the chat.

```json
{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_sandbox_app_key",
        "WEBULL_APP_SECRET": "your_sandbox_app_secret",
        "WEBULL_REGION_ID": "us",
        "WEBULL_ENVIRONMENT": "uat",
        "WEBULL_TOOLSETS": "account,market-data",
        "WEBULL_AUDIT_LOG_FILE": "/absolute/path/webull-mcp-audit.log"
      }
    }
  }
}
```

The Local MCP page says the auth step is only required when two-factor authentication is on. The command it prints is `uvx webull-openapi-mcp auth`. You approve the request in the Webull app. The page says the token is valid for 15 days and auto-refreshes on use.

Then restart the client. The verify line on that page is: Get my account list.

The [readme security section](https://github.com/webull-inc/webull-openapi-mcp) says to prefer the env block over a `.env` file. A `.env` file in the workspace could be read by the assistant through the IDE. The Local MCP page says never to share the app key, app secret, or token via chat.

## What is the difference between uat and prod?

uat is sandbox. The SDK page lists api.sandbox.webull.com as the test trading host, and the Local MCP source registers that US host when the environment is uat. prod is production. The setup page says no application is required and points at shared test credentials. The SDK page lists none, and points at a test-account application.

The [SDKs and Tools page](https://developer.webull.com/apis/docs/sdk) lists `api.sandbox.webull.com` as the test Trading API host, and `api.webull.com` as the production Trading API host. In the published Local MCP source, [`sdk_client.py`](https://github.com/webull-inc/webull-openapi-mcp/blob/main/webull_openapi_mcp/sdk_client.py) registers `api.sandbox.webull.com` for the US region when the environment is uat. For prod, that file says the SDK uses its built-in production endpoints.

The [example env file](https://github.com/webull-inc/webull-openapi-mcp/blob/main/.env.example) comments that the uat default is paper trading, and that prod is for live trading. The docs call uat sandbox and point at test credentials. This page follows the docs and says sandbox.

Sandbox keys, as the pages stood on 2026-10-17:

The [Local MCP page](https://developer.webull.com/apis/docs/AI-friendly-Resources/local-mcp) says "No application required. Use the publicly shared test credentials to get started immediately." It links the SDKs and Tools page. That page does not print a shared key. It says you can refer to the [Trading API Application](https://developer.webull.com/apis/docs/authentication/IndividualApplicationAPI) page to create a test account.

The retail section of the application page says an account has to be open before the API application. It then describes a button labeled "Using OpenAPI service in Paper Trading", which goes to the Sandbox Trading page. There you apply for the Sandbox Trading API. The page says that application is approved automatically and typically finishes within a few minutes, and that you then generate an App Key and an App Secret. The institutional section is a separate path. It says sandbox data does not sync to production, and that the two environments are fully isolated.

Use a sandbox key in the uat config. This page does not reprint a shared key, because the SDK page does not show one.

## How do I make the Webull MCP read-only?

Set WEBULL_TOOLSETS to account,market-data. The Local MCP page says that disables trading tools. On 2026-10-17, package 1.2.5's tool list with that value had no place, replace, preview, or cancel_order tool. Watchlist create, edit, and delete tools were still listed. After a restart, ask the client to list its tools.

The [Local MCP page](https://developer.webull.com/apis/docs/AI-friendly-Resources/local-mcp) says: for read-only access (market data and account only), set `WEBULL_TOOLSETS=account,market-data` to disable trading tools. The [readme](https://github.com/webull-inc/webull-openapi-mcp) lists the valid values as `account`, `market-data`, `trading`, and `instrument`.

On 2026-10-17, `uvx webull-openapi-mcp tools` with `WEBULL_TOOLSETS=account,market-data` was run against webull-openapi-mcp 1.2.5, the build uvx installed that day. The list had no `place_` tool, no `replace_` tool, no `preview_` tool, and no `cancel_order`. It still listed watchlist writes: `create_watchlist`, `delete_watchlist`, `add_watchlist_instruments`, `remove_watchlist_instruments`, `update_watchlist`, and `update_watchlist_instruments`. So the setting drops trading tools. It does not drop every write.

That check was the server's own tool list, not a click-through in Claude Desktop. After you restart the client, ask it to list its tools. If a place tool is still there, do not treat the config as read-only.

## Which Webull MCP tools send an order?

place_stock_order and the other place tools on the Local MCP table submit an order. preview_stock_order and preview_option_order do not. The replace tools modify an existing order, and cancel_order cancels an unfilled one. Those names were in the package tool list on 2026-10-17. Cloud MCP is separate: its trading tools create an instruction you confirm in the Webull app or desktop.

From the endpoint table on the [Local MCP page](https://developer.webull.com/apis/docs/AI-friendly-Resources/local-mcp):

| Kind | Tools the page names | What the page says |
| --- | --- | --- |
| Submit | place_stock_order, place_option_single_order, place_option_strategy_order, place_futures_order, place_crypto_order, place_event_order, place_algo_order, place_stock_combo_order | Place an order. place_stock_order is "Place a stock order (single, non-combo)." |
| Do not submit | preview_stock_order, preview_option_order | preview_stock_order is "Preview a stock order without submitting." preview_option_order is "Preview an option order without submitting." |
| Change an existing order | replace_stock_order, replace_option_order, replace_futures_order, replace_event_order, cancel_order | The replace lines say modify an existing order. cancel_order says cancel an unfilled order. |

Those names were present when the full tool list was printed on 2026-10-17. The page's trading examples ("Buy 100 shares of AAPL at market price") are not a sandbox drill. Stage 1 leaves the trading tools off.

## What limits does the Webull MCP enforce?

The Local MCP page defaults WEBULL_MAX_ORDER_NOTIONAL_USD to 10000, WEBULL_MAX_ORDER_QUANTITY to 1000, and WEBULL_SYMBOL_WHITELIST to no restriction. Those caps cover one order's value, size, and symbols. The page does not say they cover daily loss, open positions, or whether production is armed. Put those in limits.md and run the order through Agent Order Check.

The [Local MCP configuration table](https://developer.webull.com/apis/docs/AI-friendly-Resources/local-mcp) is the source for those three defaults. The docs name the caps. They do not say whether an order over a cap is rejected or cut down. This page does not either.

Stage 2 is still uat. It turns trading tools on for a rehearsal. The numbers are an example for that rehearsal. They are not a position size. Change only these lines from stage 1:

```json
"WEBULL_TOOLSETS": "account,market-data,trading,instrument",
"WEBULL_SYMBOL_WHITELIST": "AAPL",
"WEBULL_MAX_ORDER_QUANTITY": "1",
"WEBULL_MAX_ORDER_NOTIONAL_USD": "500"
```

Daily loss, open positions, and whether live trading is armed belong in a file the agent does not write. That file, and what a checker rejects, is the [guardrails guide](/guides/ai-agent-trading-guardrails). Before the agent sends the order, paste it into the [Agent Order Check](/check).

## Should I use Cloud MCP or Local MCP?

Cloud MCP is a hosted server. You connect with OAuth at the URL on Webull's Cloud page, which says that URL is a configuration link and cannot be opened directly. Its trading tools create an instruction you confirm in the Webull app or desktop. Local MCP runs on your machine through uvx, with an app key. Its place tools submit.

The [Cloud MCP page](https://developer.webull.com/apis/docs/AI-friendly-Resources/mcp) prints the server URL `https://api.webull.com/mcp` and says it is a configuration link that cannot be opened directly. `place_stock_instruction` on that page is "Create a stock order instruction (requires confirmation in Webull APP / Desktop)." The option, futures, crypto, event, and algo instruction tools use the same confirmation line.

| | Cloud MCP | Local MCP |
| --- | --- | --- |
| How it runs | Hosted. OAuth. The URL above is the configuration link. | A local process: `uvx webull-openapi-mcp`, with an app key and app secret. |
| What an order tool does | Creates an instruction you confirm in the Webull app or desktop. | The place tools submit an order. |

The Cloud page does not state a sandbox host. The uat switch on this page is the Local MCP setting.

## What should I check before switching to prod?

Stay on uat until you choose otherwise. Before the environment line says prod, set the caps and a symbol whitelist, keep limits.md outside the agent, run the order through Agent Order Check, and set an audit log path. One sandbox round trip should already be in that log. This page does not include a prod config.

Moving to prod is your decision. There is no prod snippet on this page. Check these first:

1. The environment line says prod on purpose. The [readme](https://github.com/webull-inc/webull-openapi-mcp) describes `webull-openapi-mcp status` as "Show configuration status". On 2026-10-17, `uvx webull-openapi-mcp status` (package 1.2.5) printed an Environment line: uat when `WEBULL_ENVIRONMENT` was uat, and prod when it was prod. With the variable unset and no `.env` file, it printed uat, which is the default, not a reading of the client config. Run it in a shell that has the same variable the client will use.
2. The caps are set, and a symbol whitelist is set.
3. limits.md exists, and the agent does not write it. The [guardrails guide](/guides/ai-agent-trading-guardrails) is that file and `validate_limits.py`.
4. The order has been through the [Agent Order Check](/check).
5. `WEBULL_AUDIT_LOG_FILE` is set. The [readme configuration table](https://github.com/webull-inc/webull-openapi-mcp) says the default is stderr only.
6. One uat round trip is already in that log.

Read the [paper-live gate](/skills/paper-live-gate) and the [risk gate](/skills/risk-gate) before the environment line changes. The [Desk Kit](/desk-kit) is the paid checker for a desk.

## Questions people ask

### Is the Webull MCP live by default?

No. The documented default is uat, which the Local MCP page calls sandbox. The Cursor, Claude Desktop, and Kiro examples on that page set prod, so a pasted example is production.

### Where do I put my Webull app key?

In the env block of the MCP client config. The Local MCP page says never to share the app key, app secret, or token in chat. The project readme says to prefer that env block over a .env file, because a file in the workspace could be read by the assistant.

### Can the agent place an order without asking me?

On Local MCP, place_stock_order and the other place tools submit an order. The Local MCP page does not say the server asks you first. On Cloud MCP, place_stock_instruction and the other instruction tools create an order you confirm in the Webull app or desktop.

### How do I turn off trading tools?

Set WEBULL_TOOLSETS to account,market-data. The Local MCP page says that disables trading tools. On 2026-10-17 the server's tool list with that setting omitted place, replace, preview, and cancel_order. Watchlist create, edit, and delete tools were still listed.

### How long does the 2FA token last?

Webull says the token is valid for 15 days, and that it auto-refreshes on use. The auth command is only required when the account has two-factor authentication turned on.

### Do Webull's order caps replace my own limits?

No. The documented caps limit one order's quantity and its notional value. A symbol whitelist limits which symbols are allowed. The page does not say those caps track daily loss or open positions. Keep those in a limits file the agent does not write, and run the order through Agent Order Check.

## Sources checked

Checked on 2026-10-17.

- [Webull Local MCP](https://developer.webull.com/apis/docs/AI-friendly-Resources/local-mcp)
- [Webull Cloud MCP](https://developer.webull.com/apis/docs/AI-friendly-Resources/mcp)
- [Webull SDKs and Tools](https://developer.webull.com/apis/docs/sdk)
- [Trading API Application](https://developer.webull.com/apis/docs/authentication/IndividualApplicationAPI)
- [webull-openapi-mcp readme](https://github.com/webull-inc/webull-openapi-mcp)
- [Example env file](https://github.com/webull-inc/webull-openapi-mcp/blob/main/.env.example)
- [UAT hosts in sdk_client.py](https://github.com/webull-inc/webull-openapi-mcp/blob/main/webull_openapi_mcp/sdk_client.py)

The [Alpaca guide](/guides/ai-agents-for-alpaca) is a separate broker page. It is not a Webull setup.

Automated trading can lose money; start on paper and set hard limits. Not financial advice.

Free check: https://theagentictrader.com/check?utm_source=md&utm_medium=agent&utm_campaign=guides-webull-mcp-setup
Weekly note on broker and agent changes: https://theagentictrader.com/subscribe?utm_source=md&utm_medium=agent&utm_campaign=guides-webull-mcp-setup
Desk Kit, $79 one-time. Full refund within 7 days: https://theagentictrader.com/desk-kit?utm_source=md&utm_medium=agent&utm_campaign=guides-webull-mcp-setup