Tracey MCP Server Troubleshooting Guide

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

Connection Issues#

Problem: MCP server not connecting

Symptoms:

• AI tool shows "No MCP servers available"
• Connection timeout errors
• "Server unreachable" messages

Solutions:

Verify the URL is correct

Correct URL:

https://mcp.tracey.dev/sse

Common mistakes:

• Missing
  Terminal

  /sse

  endpoint
• Wrong protocol (http vs https)
• Typos in domain name

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

Restart your AI tool

• Close and reopen Claude/Cursor/VS Code
• Clear any cached MCP configurations
• Re-add the server configuration

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:

Explicitly request tool usage

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

Verify tool availability

Ask:

"List all available MCP tools"

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:

Get a valid auth token

1. Visit https://connector.tracey.dev/auth
2. Complete the authentication process
3. Copy the token exactly (no extra spaces)

Include auth token in requests

Example:

"Use my auth token abc123xyz to check XDC balance"

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:

Check MetaMask installation

• Ensure MetaMask extension is installed and enabled
• MetaMask should be unlocked
• Try refreshing the page if using web interface

Clear MetaMask connection cache

1. Go to MetaMask Settings > Advanced > Reset Account
2. This clears connection cache without losing funds
3. Reconnect to the dApp

Check network settings

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

Add XDC Network if not present:

• Network Name: XDC Network
• RPC URL:
  Terminal

  https://rpc.xinfin.network

• Chain ID: 50
• Currency Symbol: XDC
• Block Explorer:
  Terminal

  https://explorer.xinfin.network

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:

Verify wallet address format

• XDC addresses start with
  Terminal

  xdc

  (native format)
• Ethereum format uses
  Terminal

  0x

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

Check network connection

• RPC endpoints might be slow or unresponsive
• Try again after a few minutes
• Verify XDC network is accessible

Cross-check with explorer

• Compare results with https://explorer.xinfin.network
• If explorer shows different data, report the issue

Transaction Issues#

Problem: Transfer transactions fail

Symptoms:

• "Transaction failed" errors
• Insufficient gas errors
• "Transaction reverted" messages

Solutions:

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

Validate addresses

• Recipient address must be valid XDC format
• Use address normalization tools if needed
• Double-check addresses before sending

Adjust gas settings

Try:

"Calculate gas fees for my transfer first"

This shows estimated costs before execution

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:

Use calculate_gas_fees tool first

Example:

"Calculate gas fees for a token transfer"

This provides accurate estimates for different transaction types

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:

Use specific tools instead of general requests

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

Break down complex requests

• Request one tool at a time for complex operations
• Wait for each response before making the next request

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:

Verify data sources

• Some data comes from external APIs that might be down
• Try again later if external services are unavailable

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
  Terminal

  *.tracey.dev

  is allowed
• WebSocket connections might need firewall configuration
• Contact your IT team if MCP traffic is blocked

Getting Help#

Before Reporting Issues

• Document the exact error message
• Note which AI tool you're using (Claude/Cursor/VS Code)
• Include the specific request that failed
• Test with simpler requests first

Support Channels

• Documentation: Check MCP Setup 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!