# Troubleshooting (/docs/troubleshooting)



## Why doesn't the server appear in my client? [#why-doesnt-the-server-appear-in-my-client]

* Confirm the config file is the right one for your client and that JSON is
  valid (a trailing comma breaks it silently).
* **Fully restart** the client after editing config. Most clients load MCP
  servers only at launch.
* Check your client's MCP/developer logs for a startup error from
  `delta-exchange-mcp`.
* If you installed the Claude Desktop bundle there is no config file to inspect.
  Each extension unpacks into its own directory under
  `~/Library/Application Support/Claude/Claude Extensions/`, alongside the
  virtualenv built at install time; that directory and the app's own log are
  where to look when a bundle installs but won't start.

## `uvx: command not found` [#uvx-command-not-found]

`uv` isn't installed or isn't on your `PATH`. Install it
([instructions](/docs#install-uv)) and restart your terminal **and**
your AI client so it inherits the updated `PATH`. Some GUI clients don't see
shell `PATH` changes until a full restart (or a reboot on macOS).

This applies to the one-click Cursor and VS Code installs too: they write the
entry for you, but the entry still launches the server through `uvx`. The Claude
Desktop bundle is the exception — it fetches its own runtime and never needs
`uv`.

## Why does `uvx delta-exchange-mcp` fail to resolve? [#why-does-uvx-delta-exchange-mcp-fail-to-resolve]

Run it directly in a terminal to see the real error:

```bash
uvx delta-exchange-mcp --help
```

A network/proxy issue or an old `uv` are the usual causes. Update uv:

```bash
uv self update
```

An old server version is another: releases before `0.4.2` do not start on a
fresh install. `uvx` resolves the newest published version on each launch; to
pin one, use `uvx "delta-exchange-mcp==VERSION"`, where `VERSION` is a
release from the [PyPI release history](https://pypi.org/project/delta-exchange-mcp/#history).

## Why does it hang when run in a terminal? [#why-does-it-hang-when-run-in-a-terminal]

Expected: bare `uvx delta-exchange-mcp` starts the MCP server and waits for a
client on stdio. Use `--help` or `--version` for a check that exits.

## Why is the bundle install slow or stuck? [#why-is-the-bundle-install-slow-or-stuck]

The first install of a bundle needs network and can take a while. Claude Desktop
resolves `uv`, downloading it if your machine has none, then fetches a Python
interpreter and the server's dependencies. The app shows this as download
progress. Subsequent installs reuse what it already fetched.

## Why am I getting authentication or signature errors? [#why-am-i-getting-authentication-or-signature-errors]

* The key and `DELTA_MCP_ENV` must match: production key → `india_prod`, testnet
  key → `india_testnet`. A mismatch is the most common cause.
* Re-check `DELTA_API_KEY` / `DELTA_API_SECRET` for stray spaces or truncation.
* If you set an IP whitelist on the key, confirm your current IP is allowed.
* Confirm the key still exists and has **Read Data** permission.

## Why do account tools return empty results? [#why-do-account-tools-return-empty-results]

* You may have no open positions/orders. Try a market-data tool first to
  confirm the connection works.
* **\~90-day default window:** `get_fills`, `get_wallet_transactions`, and
  `bulk_fills_export` return only the last \~90 days unless you pass a
  `start_time_us`. If older trades are missing, state an explicit date range in
  your prompt.
* Pagination: history tools return a page at a time. Ask the model to follow
  `meta.after` cursors for the full set, or use `bulk_fills_export` for fills.
* Timestamps are in **microseconds** for fills/orders/wallet history. A wrong
  unit in a time filter silently returns nothing.

## Why do market-data tools work when account tools don't? [#why-do-market-data-tools-work-when-account-tools-dont]

That means the server is running but the key isn't being read. Look for an
account tool such as `get_positions` in your client's tool list: if it is
missing, no credentials reached the server. Verify the `env` block is present
in the config and that you restarted the client. Market data needs no key, so
it works regardless.

The tool list stops there. It tells you whether a key arrived, not what that
key may do, because the account and trading tools register together whatever permission
it carries.

Or ask the assistant to call `get_connection_status`, which answers the same
question directly.

Setting only one of `DELTA_API_KEY` / `DELTA_API_SECRET` has the same effect as
setting neither: both are needed to sign a request, so the account tools stay
unregistered. The server says so on startup — look for a line naming the one
that's missing in your client's MCP logs.

## Why doesn't the key form appear in the chat? [#why-doesnt-the-key-form-appear-in-the-chat]

You asked the assistant to connect your account and it replied with a file path
and a command instead of showing a form.

That is the intended fallback rather than a failure. Rendering a form inline is
an optional part of MCP that only some clients implement, and the server cannot
tell in advance which ones do, so it always returns working instructions
alongside the form. On a client that shows nothing, you see only the
instructions. Claude Desktop and the Codex desktop app render the form today.

Use either of the other two routes, which write the same file the form would
have. Run `uvx delta-exchange-mcp login`, or open
`~/.delta-exchange-mcp/config.env` and fill in the three lines waiting in it.
[Authentication](/docs/authentication) covers both.

## Why can't the assistant see my account after the form saved my key? [#the-form-saved-my-key-but-the-assistant-still-cannot-see-my-account]

The form reports that it saved, and it names a setting your client sets in its
own configuration.

Both statements are true, and together they are the whole failure. A value in
your client's MCP entry, or in the fields it asked you to fill in when you
installed it, is read before the shared file and wins over it. So the form
checked your key against Delta, saved it correctly, and the server carries on
signing with whatever your client passes. Restarting does not help, because the
client passes its own value again at every launch.

This is the one case where the install builder's own convenience works against
you: if you typed your key into the generated config, that key is the one in
force no matter what the form saves afterwards.

Clear those fields from that client's entry and restart it. The message the form
shows names which setting is at fault. `uvx delta-exchange-mcp login` runs the
same check and warns on stderr, though it reports what your **shell** is setting,
because that is the environment it can see.

## Why don't the trading tools appear? [#why-dont-the-trading-tools-appear]

They register with the account tools, whenever `DELTA_API_KEY` and
`DELTA_API_SECRET` both reach the server. If the account tools are missing too,
the key is not being read: see
[the question above](#why-do-market-data-tools-work-when-account-tools-dont).

There is no mode to switch on. A key saved through the in-chat form or the shared
file arms both groups in the running server. Some clients, Claude Desktop among
them, show the new tools only after you restart the client. A key you put in your
client's `env` block arrives only when the client relaunches the server.

## Why does a trading tool return a permission or IP error? [#why-does-a-trading-tool-return-a-permission-or-ip-error]

* The API key must have **Trading** permission enabled in Delta API management.
  A Read Data key lists the trading tools and Delta rejects what they send with
  `Unauthorized`. Create a
  key with the permission you want; there is no setting here that grants it.
* The requesting IP must be **whitelisted** on the key. The error context names
  the IP Delta saw, so add that one to the key's whitelist. Delta requires a
  whitelist entry on every Trading key.
* After a mutation **signature error**, don't retry blindly: mutations are never
  auto-retried because the first attempt may have reached the exchange. Check
  `get_open_orders` / `get_positions` before re-sending.

## Why does my order rest at a different price than I asked for? [#why-does-my-order-rest-at-a-different-price-than-i-asked-for]

Prices are sent to Delta exactly as given, and Delta moves a price that is off the
product's tick onto the tick. The `limit_price` in the response is the price that
applies. Read the tick from `get_product` and price to it.

## Where is the record of what the assistant sent? [#where-is-the-record-of-what-the-assistant-sent]

Delta's own order and fill history. The server keeps no local log of orders: use
`get_order_history` and `get_fills`, or the Delta app.

## Why am I hitting rate limits or intermittent failures? [#why-am-i-hitting-rate-limits-or-intermittent-failures]

Delta's API is rate-limited. Rapid-fire prompts across many symbols can trip
limits; space requests out or narrow the query. Transient errors usually clear
on retry.

## How do I update the server? [#how-do-i-update-the-server]

On the `uvx` paths — including the one-click Cursor and VS Code installs — `uvx`
caches the package. To force the latest version:

```bash
uvx --refresh delta-exchange-mcp --help
```

If you installed the Claude Desktop bundle, download the
[latest bundle](https://github.com/delta-exchange/delta-exchange-mcp/releases/latest/download/delta-exchange-mcp.mcpb)
and open it again.

## How do I capture a debug log? [#capture-a-debug-log]

When a tool returns something unexpected, the server can record exactly what it
sent and received. Add `DELTA_MCP_DEBUG` to the same `env` block as your
credentials — or, in the Claude Desktop bundle, use a hand-written config, since
the install form has no field for it:

```json title="your client's MCP config — env block"
"env": {
  "DELTA_MCP_ENV": "india_prod",
  "DELTA_MCP_DEBUG": "1"
}
```

Restart the client and repeat the action. Each HTTP call — request URL with its
filter params, response status, and response body — is written to
`~/.delta-exchange-mcp/logs/`. Override the location with `DELTA_MCP_DEBUG_FILE`.

To find the file, just ask: **"where is the debug log?"** Debug mode registers a
`get_debug_status` tool that returns the exact path, and the path is also in the
startup line your client's MCP logs capture. That extra tool is the one thing
debug mode changes about the tool list.

<Callout type="warn" title="Read it before you send it">
  The log never records your API key, secret, or request signatures. It does record
  response bodies, which carry your balances, positions, and transactions — so
  review it before attaching it to an issue.
</Callout>

## Still stuck? [#still-stuck]

Open an issue on
[github.com/delta-exchange/delta-exchange-mcp](https://github.com/delta-exchange/delta-exchange-mcp/issues)
with your client, OS, and the error from the logs. A debug log from the section
above turns a vague report into a reproducible one.