Troubleshooting

Common issues and solutions when using Universal Crypto MCP.

🔴 Connection Issues

MCP Server Not Starting

Symptom: Server doesn't start, no response from Claude/ChatGPT

Solutions:

Check Node.js version
```
node --version  # Must be >= 18.0.0
```

Reinstall dependencies

rm -rf node_modules package-lock.json
npm install

Check for port conflicts (HTTP/SSE mode)

lsof -i :3001  # Check if port is in use

Verify config path (Claude Desktop)

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

# Linux
cat ~/.config/Claude/claude_desktop_config.json

"Tool not found" Error

Symptom: Claude says it can't find a tool

Solutions:

Restart Claude Desktop after config changes
Check tool name spelling - use exact names from docs

Verify server is running:

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx @nirholas/universal-crypto-mcp

ChatGPT Not Connecting (HTTP Mode)

Symptom: ChatGPT can't reach the MCP server

Solutions:

Ensure server is running:

npx @nirholas/universal-crypto-mcp --http
# Should see: "HTTP server listening on port 3001"

Check firewall settings - allow port 3001
Verify URL in ChatGPT:
Correct: http://localhost:3001/mcp
Wrong: http://localhost:3001 (missing /mcp)

Try with explicit host:

HOST=0.0.0.0 npx @nirholas/universal-crypto-mcp --http

🟡 Transaction Errors

"Insufficient Funds"

Symptom: Transaction fails with insufficient balance

Solutions:

Check native token balance for gas:
```
What's my ETH balance on Arbitrum?
```
Check token balance:
```
What's my USDC balance on Arbitrum?
```
Reduce amount to leave room for gas

"Transaction Reverted"

Symptom: Transaction submitted but reverted on-chain

Common Causes:

Cause	Solution
Slippage too low	Increase slippage to 1-3%
Token has transfer tax	Account for tax in amount
Approval not set	Approve token first
Contract paused	Check if protocol is active
Price moved	Get fresh quote and retry

Debug Steps:

Simulate first:

Simulate swapping 100 USDC for ETH on Arbitrum

Check token security:
```
Is this token safe? 0x...
```

"Nonce Too Low"

Symptom: Transaction rejected with nonce error

Solutions:

Wait for pending transactions to confirm

Cancel pending transaction:

Cancel my pending transaction on Ethereum

Speed up transaction:

Speed up my pending transaction with 20% more gas

"Gas Estimation Failed"

Symptom: Can't estimate gas for transaction

Solutions:

Check if contract allows the operation
Verify you have required approvals
Try with explicit gas limit:
```
{
  "gasLimit": "500000"
}
```

🟠 API & Data Issues

"API Key Required"

Symptom: Tool returns API key error

Solutions:

API	How to Get Key
CoinGecko	coingecko.com/api
LunarCrush	lunarcrush.com/developers
CryptoPanic	cryptopanic.com/developers

Set in environment:

export COINGECKO_API_KEY=your_key_here

Or in Claude config:

{
  "mcpServers": {
    "universal-crypto-mcp": {
      "env": {
        "COINGECKO_API_KEY": "your_key_here"
      }
    }
  }
}

"Rate Limited"

Symptom: API returns 429 error

Solutions:

Wait and retry - usually 1 minute
Use API key for higher limits
Reduce request frequency
Use cached data when possible

Stale/Wrong Price Data

Symptom: Prices seem outdated or incorrect

Solutions:

Specify the source:
```
Get Bitcoin price from CoinGecko
```
Check multiple sources:
```
Compare ETH price across exchanges
```

Use on-chain price:

Get ETH/USDC price from Uniswap on Ethereum

🔵 Security Issues

"Honeypot Detected"

Symptom: Token flagged as honeypot

What It Means: - Token cannot be sold after buying - Common scam tactic

Action: - ❌ DO NOT BUY this token - Report to community

"High Risk Score"

Symptom: Token has risk score > 7/10

Check These Factors:

Factor	Why It's Risky
Ownership not renounced	Owner can rug
Hidden mint function	Unlimited supply
Blacklist function	Can block your wallet
High holder concentration	Whale dump risk
Liquidity not locked	Can pull liquidity

Action: - Proceed with extreme caution - Never invest more than you can lose

Approval Concerns

Symptom: Worried about token approvals

Check Your Approvals:

Show all my token approvals on Ethereum

Revoke Suspicious Approvals:

Revoke approval for 0xSuspiciousContract on my USDC

🟣 Environment Issues

Private Key Not Working

Symptom: Transactions fail with signing errors

Checklist:

Format check - Must start with 0x:

# Correct
PRIVATE_KEY=0x123abc...

# Wrong
PRIVATE_KEY=123abc...

No quotes in .env:

# Correct
PRIVATE_KEY=0x123abc...

# Wrong
PRIVATE_KEY="0x123abc..."

Correct length - 64 hex characters after 0x
Test with read-only first:
```
What's the balance of my wallet?
```

Wrong Network

Symptom: Operations happening on wrong chain

Solutions:

Always specify network:

Swap 1 ETH for USDC on Arbitrum  # Good
Swap 1 ETH for USDC              # Ambiguous

Check supported networks:
```
List all supported networks
```

🔧 Debug Mode

Enable Verbose Logging

LOG_LEVEL=DEBUG npx @nirholas/universal-crypto-mcp

Use MCP Inspector

npx @modelcontextprotocol/inspector npx @nirholas/universal-crypto-mcp

This opens a web UI where you can: - See all available tools - Test tools manually - View request/response logs

📞 Getting Help

Before Asking for Help

✅ Check this troubleshooting guide
✅ Search existing issues

✅ Try with latest version:

npx @nirholas/universal-crypto-mcp@latest

How to Report a Bug

Include:

Environment:
Node.js version
OS (macOS/Windows/Linux)
Client (Claude/ChatGPT/Cursor)
Steps to reproduce
Expected vs actual behavior
Error messages (full text)
Relevant logs (with LOG_LEVEL=DEBUG)

Open an Issue →

💡 Pro Tips

Speed Up Transactions

Submit this swap privately via Flashbots on Ethereum

Avoid MEV

Execute swap with MEV protection enabled

Batch Operations

Get balances for ETH, USDC, and WBTC on Arbitrum in one call

Test Before Mainnet

Swap 0.01 ETH for USDC on Arbitrum Sepolia testnet