Skip to main content
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

  • 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.
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.
  • Verify the key at 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.
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:
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.
Restarting the client alone is often not enough, because the stored credentials survive a restart. Removing the server entry is what clears them.

​
Connection

  • 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.
  • 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.

​
Results

  • Rephrase more specifically by naming the metric, the entity, and the timeframe. See What to ask.
  • 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.
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.

​
Getting help

  • API keys: app.blockworks.com/account/api
  • Documentation: 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.