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

# Troubleshooting

> Fixes for authentication loops, invalid API keys, stale OAuth credentials, and connection problems with the Blockworks MCP server.

Most MCP problems are one of three things: the client cannot open the OAuth flow, the API key is not valid for the
key entry step, or the client is holding on to credentials from an earlier connection. Work through the section
that matches your symptom.

## Authentication

<AccordionGroup>
  <Accordion title="The OAuth window never opens">
    * Confirm your client supports **remote** MCP servers with OAuth 2.0. Clients limited to local `stdio` servers
      cannot complete this flow.
    * Check that popups are not blocked in your default browser.
    * Restart the MCP client and reconnect. Some clients only attempt the flow at startup or on the first tool
      call.
    * If your client has an explicit authenticate action (in Claude Code, `/mcp`), trigger the flow from there
      rather than waiting for it to start on its own.
  </Accordion>

  <Accordion title="You are stuck in a loop, re-authenticating over and over">
    This usually means the client is not persisting the credentials it receives.

    * Complete the browser flow and wait for it to redirect back before switching windows or closing the tab.
    * Make sure only one instance of the client is running. A second instance can overwrite the stored credentials
      of the first.
    * Remove the server from your client, restart the client, then add
      `https://mcp.blockworks.com/mcp` again and re-authenticate from a clean state.
  </Accordion>

  <Accordion title="Your API key is rejected">
    * Verify the key at [app.blockworks.com/account/api](https://app.blockworks.com/account/api), and confirm it
      is active and has not been rotated or revoked.
    * Copy the key fresh from the account page. Truncated keys and trailing whitespace are the most common cause.
    * Confirm the key has access to the data you are trying to reach. Every key sees the same five tools, but the
      models those tools can read follow the key's entitlements, so a valid key can still hit an access error on a
      specific dataset.
  </Accordion>

  <Accordion title="It worked before and suddenly stopped">
    Clients cache OAuth credentials, and those can go stale, most often after you rotate or revoke the API key
    they were issued against.

    Remove and re-add the server so the client discards the cached credentials and runs a fresh flow:

    ```bash theme={null}
    # Claude Code
    claude mcp remove blockworks
    claude mcp add --transport http blockworks https://mcp.blockworks.com/mcp
    ```

    In connector-based clients (Claude, Claude Desktop, ChatGPT), delete the Blockworks connector, restart the
    client, then add it again. In Cursor, remove the entry from `mcp.json`, restart, and re-add it.

    <Warning>
      Restarting the client alone is often not enough, because the stored credentials survive a restart. Removing
      the server entry is what clears them.
    </Warning>
  </Accordion>
</AccordionGroup>

## Connection

<AccordionGroup>
  <Accordion title="The server is unreachable">
    * Check that `https://mcp.blockworks.com` is reachable from your network. Corporate VPNs and egress proxies
      frequently block unfamiliar hosts.
    * Confirm the URL is exactly `https://mcp.blockworks.com/mcp`, including the `/mcp` path.
    * Retry in a few minutes in case of a transient outage.
  </Accordion>

  <Accordion title="No Blockworks tools appear in the assistant">
    * Ask directly: `What Blockworks tools do you have available?` An empty answer means the server connected
      without completing authentication, or did not connect at all.
    * Check your client's server list for the connection state (`claude mcp list` in Claude Code, the MCP or
      connectors settings pane elsewhere).
    * In clients where connectors are enabled per conversation, make sure Blockworks is toggled on for the chat you
      are in, then start a new conversation so the tool list is refreshed.
  </Accordion>
</AccordionGroup>

## Results

<AccordionGroup>
  <Accordion title="Empty or unexpected answers">
    * Rephrase more specifically by naming the metric, the entity, and the timeframe. See
      [What to ask](/mcp/prompts).
    * Break a multi-part question into several focused ones.
    * Confirm the data you want is covered. Asking "what Blockworks datasets cover this?" first makes the
      assistant read the catalog and tells you what is queryable under your key.
  </Accordion>

  <Accordion title="The assistant answers without calling a tool">
    Models sometimes answer from their own knowledge, which will be stale for anything market-related. Ask it
    explicitly to use the Blockworks tools, and request the underlying figures so it is obvious where the answer
    came from.
  </Accordion>
</AccordionGroup>

## Getting help

* **API keys**: [app.blockworks.com/account/api](https://app.blockworks.com/account/api)
* **Documentation**: [docs.blockworks.com](https://docs.blockworks.com)
* **Still stuck**: reach out to your Blockworks account team with your client name and version, the step that
  fails, and anything your client logs during the connection attempt.