Tracey MCP Server Troubleshooting Guide

This guide helps resolve common issues when connecting and using the Tracey MCP server with AI tools.

Written By Abilash S

Last updated 3 months ago

Connection Issues

Problem: MCP server not connecting

Symptoms:

  • AI tool shows "No MCP servers available"

  • Connection timeout errors

  • "Server unreachable" messages

Solutions:

  1. Verify the URL is correct

    Correct URL: https://mcp.tracey.dev/sse Common mistakes: - Missing /sse endpoint - Wrong protocol (http vs https) - Typos in domain name

  2. Check your internet connection

    • Test by visiting https://mcp.tracey.dev in your browser

    • Verify you can access other HTTPS sites

    • Check if you're behind a corporate firewall

  3. Restart your AI tool

    • Close and reopen Claude/Cursor/VS Code

    • Clear any cached MCP configurations

    • Re-add the server configuration

  4. Check AI tool MCP support

    • Ensure you're using a version that supports MCP

    • Update to the latest version if needed

    • Verify MCP is enabled in settings

Problem: Tools not appearing in AI responses

Symptoms:

  • AI doesn't use Tracey tools when appropriate

  • "I don't have access to blockchain tools" responses

  • Generic answers instead of using real data

Solutions:

  1. Explicitly request tool usage

    Instead of: "What's the XDC price?" Try: "Use the get_xdc_price tool to check current XDC price"

  2. Verify tool availability

    Ask: "List all available MCP tools" You should see Tracey's blockchain tools listed

  3. Check connector selection (Claude)

    • Ensure you've selected the Tracey connector in the attachments panel

    • The connector icon should be highlighted/active

    • Try disconnecting and reconnecting the connector

Problem: Authentication errors

Symptoms:

  • "Invalid auth token" errors

  • Limited functionality messages

  • "Authentication required" responses

Solutions:

  1. Get a valid auth token

  2. Include auth token in requests

    Example: "Use my auth token abc123xyz to check XDC balance"

  3. Verify token hasn't expired

    • Auth tokens may have expiration dates

    • Get a fresh token if needed

    • Check for any token format requirements

Wallet Connection Issues

Problem: MetaMask connection fails

Symptoms:

  • "Could not connect to MetaMask" errors

  • Wallet popup doesn't appear

  • Connection hangs indefinitely

Solutions:

  1. Check MetaMask installation

    • Ensure MetaMask extension is installed and enabled

    • MetaMask should be unlocked

    • Try refreshing the page if using web interface

  2. Clear MetaMask connection cache

    • Go to MetaMask Settings > Advanced > Reset Account

    • This clears connection cache without losing funds

    • Reconnect to the dApp

  3. Check network settings

    • Ensure MetaMask is on XDC Network (Chain ID: 50)

    • Add XDC Network if not present:

      Network Name: XDC Network RPC URL: https://rpc.xinfin.network Chain ID: 50 Currency Symbol: XDC Block Explorer: https://explorer.xinfin.network

  4. Use specific client ID for isolation

    Try: "Connect MetaMask with client_id='my-device'" This ensures session isolation on shared computers

Problem: Wallet shows wrong balance or transactions

Symptoms:

  • Balance shows 0 when wallet has funds

  • Missing recent transactions

  • Incorrect token balances

Solutions:

  1. Verify wallet address format

    • XDC addresses start with 'xdc' (native format)

    • Ethereum format uses '0x' prefix

    • Both formats should work, but verify the correct one is being used

  2. Check network connection

    • RPC endpoints might be slow or unresponsive

    • Try again after a few minutes

    • Verify XDC network is accessible

  3. Cross-check with explorer

Transaction Issues

Problem: Transfer transactions fail

Symptoms:

  • "Transaction failed" errors

  • Insufficient gas errors

  • "Transaction reverted" messages

Solutions:

  1. Check sufficient balance

    • Ensure you have enough XDC for the transfer amount

    • Account for gas fees (usually very low on XDC)

    • Verify token balance for XRC20 transfers

  2. Validate addresses

    • Recipient address must be valid XDC format

    • Use address normalization tools if needed

    • Double-check addresses before sending

  3. Adjust gas settings

    Try: "Calculate gas fees for my transfer first" This shows estimated costs before execution

  4. Check network congestion

    • XDC network is usually fast, but check current status

    • Try again during off-peak hours if needed

Problem: Gas estimation errors

Symptoms:

  • "Cannot estimate gas" errors

  • Extremely high gas estimates

  • Gas estimation timeout

Solutions:

  1. Use calculate_gas_fees tool first

    Example: "Calculate gas fees for a token transfer" This provides accurate estimates for different transaction types

  2. Check contract interaction

    • Ensure contract addresses are correct

    • Verify contract is active and not paused

    • Check if contract has sufficient allowance

Performance Issues

Problem: Slow response times

Symptoms:

  • Long delays before tool responses

  • Timeout errors

  • "Server busy" messages

Solutions:

  1. Use specific tools instead of general requests

    Instead of: "Tell me about my portfolio" Try: "Use token_portfolio tool to check my holdings"

  2. Break down complex requests

    • Request one tool at a time for complex operations

    • Wait for each response before making the next request

  3. Check rate limits

    • Some tools have rate limiting

    • Space out requests if you're making many in succession

    • Use auth token for higher limits

Problem: Incomplete or partial data

Symptoms:

  • Missing token information

  • Partial balance data

  • Empty transaction history

Solutions:

  1. Verify data sources

    • Some data comes from external APIs that might be down

    • Try again later if external services are unavailable

  2. Use multiple verification methods

    Example: Check balance with both balance tools and portfolio tools Cross-reference with blockchain explorer

Advanced Troubleshooting

Debug Mode

Enable debug information in your requests:

Example: "Check XDC balance with debug information" This provides additional technical details about the request

Manual Tool Testing

Test individual tools to isolate issues:

1. "Test the get_xdc_price tool" 2. "Test the xdc_network_info tool" 3. "Test the calculator tool" (simple baseline test)

Clear All Sessions

If you're experiencing persistent issues:

1. "Disconnect all wallets" 2. "Clear any cached session data" 3. Restart your AI tool 4. Reconnect from scratch

Network Configuration

For corporate/restricted networks:

  • Ensure HTTPS traffic to *.tracey.dev is allowed

  • WebSocket connections might need firewall configuration

  • Contact your IT team if MCP traffic is blocked

Getting Help

Before Reporting Issues

  1. Document the exact error message

  2. Note which AI tool you're using (Claude/Cursor/VS Code)

  3. Include the specific request that failed

  4. Test with simpler requests first

Support Channels

  • Documentation: Check MCP_SETUP.md for setup issues

  • Discord Community: Join our support Discord

  • GitHub Issues: Report bugs at the project repository

  • Email Support: contact@tracey.dev for urgent issues

Useful Debug Information

When reporting issues, include:

- AI tool and version - Operating system - Browser (if applicable) - Exact error messages - Steps to reproduce - Whether authentication token is being used - Network environment (home/corporate/mobile)

Most issues are resolved by verifying the MCP server URL and ensuring proper authentication. If problems persist, don't hesitate to reach out for support!