Troubleshooting Guide

Connection Issues

Server Not Responding

Symptoms:

  • Tools timeout or return no response
  • Error: “Failed to connect to MCP server”
  • Claude reports server is unavailable

Solutions:

  1. Restart the server by re-launching your MCP client, or run it directly: 
    npm run mcp
  2. Check logs for errors by enabling verbose logging: 
    export LOG_LEVEL=debug
npm run mcp
  3. Verify your environment variables (read by src/config.ts) are set correctly

Network Connectivity Problems

Symptoms:

  • Error: “Network request failed”
  • Timeouts when fetching from instances
  • Intermittent connection issues

Solutions:

  1. Check internet connection
  2. Test instance accessibility: 
    curl -I https://mastodon.social
  3. Increase timeout settings in config

Access and Permission Issues

Actor Not Found

Symptoms:

  • Error: “Actor not found”
  • Error: “Failed to resolve actor”
  • Empty results when searching for known actors

Solutions:

  1. Verify actor format: 
    # Correct formats:
@username@instance.com
https://instance.com/users/username
https://instance.com/@username
  2. Check if actor exists: 
    curl https://instance.com/.well-known/webfinger?resource=acct:username@instance.com
  3. Try alternative discovery methods
  4. Restart the server to flush the in-memory actor cache (cache TTL also expires naturally; configure via CACHE_TTL).

Rate Limiting

Symptoms:

  • Error: “Rate limit exceeded”
  • HTTP 429 responses
  • Requests being throttled

Solutions:

  1. Wait before retrying (usually 15 minutes)
  2. Reduce request frequency
  3. Use different instances to distribute load
  4. Check rate limit headers: 
    curl -I https://instance.com/api/v1/accounts/lookup

Private Content Access

Symptoms:

  • Error: “Access denied”
  • Empty timelines for known active accounts
  • Missing posts or limited content

Solutions:

  1. Respect privacy settings - this is expected behavior
  2. Try public instances and accounts
  3. Use accounts with public timelines
  4. Check instance privacy policies

Configuration Issues

Invalid Configuration

Symptoms:

  • Server fails to start
  • Error: “Invalid configuration”
  • Missing required settings

Solutions:

  1. Check required environment variables — configuration is supplied via environment variables read by src/config.ts, not a config file
  2. Review configuration documentation

Claude Desktop Integration

Symptoms:

  • Tools not appearing in Claude
  • Error: “MCP server not found”
  • Connection refused errors

Solutions:

  1. Check Claude Desktop configuration: 
    # macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json
  2. Verify server path in config
  3. Restart Claude Desktop
  4. Check server logs for connection attempts

Performance Issues

Slow Response Times

Symptoms:

  • Tools take a long time to respond
  • Timeouts on large requests
  • High memory usage

Solutions:

  1. Restart the server to flush in-memory caches, or shorten CACHE_TTL in your env.
  2. Reduce request size (limit results, narrow timelines with limit / maxId / sinceId).
  3. Use more specific queries
  4. Monitor system resources with OS-level tools (e.g., top, htop) or your deployment platform’s metrics.

Memory Issues

Symptoms:

  • Server crashes with out-of-memory errors
  • Gradual performance degradation
  • High memory usage

Solutions:

  1. Restart server regularly
  2. Reduce cache size in configuration
  3. Limit concurrent requests
  4. Monitor memory usage

Debugging Tips

Enable Verbose Logging

export LOG_LEVEL=debug
npm run mcp

This will show detailed logs for all operations.

Test Individual Components

# Test WebFinger resolution
curl "https://instance.com/.well-known/webfinger?resource=acct:user@instance.com"

# Test ActivityPub endpoint
curl -H "Accept: application/activity+json" "https://instance.com/users/username"

Check Instance Health

# Check if instance is up
curl -I https://instance.com

# Check API availability
curl https://instance.com/api/v1/instance

Monitor Network Traffic

Use browser developer tools or network monitoring tools to see actual HTTP requests and responses.

Getting Help

Before Reporting Issues

  • Check this troubleshooting guide
  • Review the basic usage guide
  • Test with known working instances (mastodon.social)
  • Collect relevant logs and error messages
  • Note your environment (OS, Node.js version, etc.)

Reporting Bugs

If you’ve found a bug, please report it on GitHub:

Report an Issue

Include:

  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Error messages and logs
  • System information

Community Support

For help, tips, bug reports, and feature requests:

GitHub Issues