> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yellow.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues with the Yellow.pro MCP server — connection, authentication, permissions, and error behaviour.

## Client shows no tools / server fails to connect

<Steps>
  <Step title="Register through the CLI">
    Use `yellow-pro setup claude-code` (or `claude mcp add` directly) rather than editing config files by hand. Claude Code reads MCP config from `~/.claude.json`, not `~/.claude/settings.json`.
  </Step>

  <Step title="Check the PATH">
    The client spawns the server without loading your shell profile, so `yellow-pro-mcp` must be on the client's `PATH`. Check with `which yellow-pro-mcp`. If the installer printed a PATH hint, add that directory to your profile and restart the client.
  </Step>

  <Step title="Restart the client">
    Servers connect at session start, so restart the client after changing any MCP config.
  </Step>

  <Step title="Verify the server starts">
    Confirm the server itself runs:

    ```bash theme={null}
    echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | yellow-pro-mcp
    ```

    A healthy response contains a `serverInfo` block and exits cleanly.
  </Step>
</Steps>

## Some tools are missing

Check `YELLOW_PRO_MODULES` character by character. Unrecognised names are silently dropped with no warning, so a plural typo like `markets,account` leaves you with account-only tools. The only accepted tokens are `market`, `account`, and `trading`.

If trading tools specifically are absent, `YELLOW_PRO_ENABLE_TRADING` is not set to `true`.

## Authentication errors

**`invalid_api_key`**

Private tools need all three of `YELLOW_PRO_API_KEY`, `YELLOW_PRO_API_SECRET`, and `YELLOW_PRO_APP_SESSION_ID`, and they must match the environment you are hitting. Staging keys do not work on production, and vice versa.

If you registered with `yellow-pro setup hermes`, the credentials were almost certainly not written — see the [hermes caveat](/mcp/installation#setup-helpers).

**`invalid_timestamp`**

Your machine clock is more than a few seconds off the exchange's. Sync it:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    sudo sntp -sS time.apple.com
    ```
  </Tab>

  <Tab title="Linux">
    Use `chrony` or `ntp` to synchronize the system clock.
  </Tab>
</Tabs>

**Permission / `403` errors on a tool that otherwise works**

The API key is missing a scope. Check it against the [scope table](/mcp/credentials#scopes-and-tools) — reads and trades are separate scopes, and spot and futures are separate again.

## Trading commands fail with "trading is disabled"

Set `YELLOW_PRO_ENABLE_TRADING=true` in the MCP client's env config. This is intentional.

<Warning>
  Do not work around this by calling the REST API directly. The flag exists so that order placement is a deliberate action. Read [Risk and safety](/mcp/risk-and-safety) first.
</Warning>

## Empty results instead of data

Almost always a timestamp unit mismatch. The three formats in use — milliseconds, Unix seconds, and RFC3339 — vary per tool, and the wrong one returns an empty set rather than an error. See the [timestamp table](/mcp/tools#timestamp-units-differ-per-tool).

## Error behaviour worth knowing

<AccordionGroup>
  <Accordion title="429 responses fail immediately">
    Rate-limit responses are thrown straight away — there is no retry and no backoff. Lowering `YELLOW_PRO_RATE_LIMIT_MS` therefore converts throttling into hard failures rather than slower requests. The default is 100 ms.
  </Accordion>

  <Accordion title="Requests time out at 30 seconds">
    There is no configurable timeout.
  </Accordion>

  <Accordion title="Error-shaped HTTP 200 responses become thrown errors">
    The exchange sometimes returns an error body with a 200 status. The client converts these into thrown errors, which is the right behaviour but will look different from raw `curl` output if you are comparing the two.
  </Accordion>

  <Accordion title="get_markets hides perpetual-side failures">
    If the perpetual side is unavailable, `get_markets` returns `{"perp":{"unavailable":"..."}}` rather than erroring — so an agent may report that no perpetual markets exist. Check for that key before believing an empty list.
  </Accordion>
</AccordionGroup>

## Still stuck

Contact [support](/community-and-resources/contact-support), or open an issue on [github.com/layer-3/yellow-pro-mcp](https://github.com/layer-3/yellow-pro-mcp). Include the `serverInfo.version` from the handshake above so the version you are running is unambiguous.