Troubleshooting

The client cannot find the tools

• Confirm uvx is installed and executable by the client
• Pin the version so behaviour does not drift: uvx --from "usmart-mcp==1.2.0" usmart-mcp
• The command stays running waiting for MCP stdio messages — that is expected; the client should launch it

Credential check fails

• Check the directory behind USMART_HOME, the required files and their permissions
• Never paste real credentials into a chat
• If channel signing fails, confirm the channel id and signing key belong to the same application

Still unauthorized after OAuth

• Confirm redirectUri matches the registered value exactly (port, path, case)
• Confirm oauth_login_status reports success
• The session lives at ~/.usmart/oauth_session.json; deleting it is a local sign-out

The callback port is taken

oauth_login listens on the port inside redirectUri (5100 by default). Register the new callback on the developer platform before switching ports, and keep it loopback-only.

Order returns 100034

OAuth write endpoints require a non-empty X-Request-Id; since 1.1.0 it is generated automatically. If it persists, check that extraHeaders is not overriding it with an empty value.

Order returns 100073

That is the platform's price-deviation risk prompt, not an auth failure. After checking the price you may pass force_entrust_flag=true — only after checking.

Queries only, no trading

Always set USMART_READONLY=1; write tools will not appear in the client's tool list.