Skip to main content
Use this page when WalletSuite MCP is installed but something is not working as expected.

​
Authentication errors

See Credentials & Authentication for the header contract, tier rules, and full error taxonomy.

​
Symptom: Authentication is required

This usually means WALLETSUITE_API_KEY is missing. Check:
  • the MCP host config file
  • environment variable spelling
  • whether the config was reloaded after editing
Fix:
  • add a valid WALLETSUITE_API_KEY
  • restart or reload the MCP host

​
Symptom: requests fail even though the server starts

This often means the API key is present but invalid for the current environment. Fix:
  • verify the key in WalletSuite
  • replace the key and reload the host

​
Missing tools

​
Symptom: only read tools are visible

This is normal if you did not set MCP_BANDS. Fix:
  • use MCP_BANDS=read,prepare if you need transaction preparation tools
  • add sign and broadcast when you are ready to enable signing

​
Symptom: signing tools are missing

Check:
  • MCP_BANDS includes sign

​
Symptom: send_transaction is missing

Check:
  • MCP_BANDS includes broadcast

​
Signing issues

Signing runs through MPC 2-of-2 (DKLS23): WalletSuite holds one key share, you hold the other, and both are required for every signature. See Key Management for how signing works.

​
Symptom: a signing tool returns a flow error

A flow-category error means a prerequisite is missing. The response includes a requiredAction with the concrete next step. Fix:
  • read the requiredAction in the error response and execute it first
  • retry the original request

​
Symptom: send_transaction is rejected

send_transaction is the destructive path and is intentionally guarded. Check:
  • MCP_BANDS includes broadcast
  • the call passes confirmBroadcast=true

​
Symptom: the transaction input is rejected

The signing tools work with raw unsigned transaction hex. Fix:
  • pass raw unsigned transaction hex only
  • prepare the payload with prepare_serialized_unsigned_tx first if you do not already have one

​
HTTP connection issues

​
Symptom: the client cannot connect to the HTTP server

Check:
  • that the server is running
  • http://localhost:3000/health
  • the full MCP path http://localhost:3000/mcp

​
Symptom: port already in use

Another local process is already using the selected port. Fix:
  • stop the conflicting process, or
  • choose another port, for example PORT=3001

​
Symptom: confusion between stateless and stateful mode

Most users should stay with MCP_HTTP_MODE=stateless. Only switch to stateful if you specifically need session-oriented behavior.

​
Host config issues

​
Symptom: the MCP host ignores the config

This often means the file location or top-level JSON shape is wrong for the host. Fix:
  • use the host-specific page in Install Guides
  • validate the JSON
  • reload the host

​
Symptom: the host still uses old settings

Fix:
  • restart the application, or
  • reload MCP servers from the host UI or CLI if the host supports it

​
Feature availability issues

​
Symptom: a tool exists but calls return a not-available error

Some backend features are feature-gated. Fix:
  • confirm whether the capability is enabled for your plan
  • fall back to the currently available read and prepare surface when possible

​
Still stuck?

If the server starts but behavior is still off:
  1. reduce the config back to the simplest working shape
  2. keep MCP_BANDS=read
  3. verify one read-only prompt first
  4. add HTTP, prepare, or signing bands only after the base setup works
If the problem persists, contact the WalletSuite team at support@walletsuite.io - include your MCP host, band config, a recent stderr snippet, and the chain you were hitting.