​

Troubleshooting

​

Connection Issues

​

Server Not Responding

• AI assistant can’t connect to MCP server
• Timeout errors
• Connection refused

https://mcp.hexjobs.com/mcp

{
  "mcpServers": {
    "hexjobs": {
      "url": "https://mcp.hexjobs.com/mcp"
    }
  }
}

​

Tools Not Available

• MCP server connects but tools don’t appear
• Assistant says “I don’t have access to job search tools”

1. Verify Connection Status
   • Check if MCP server shows as connected in your client
   • Look for green indicator or “connected” status
2. Restart Client
   • Completely quit and restart your AI assistant
   • Wait for MCP initialization
3. Check Logs
   • Claude Desktop: Look for errors in dev console
   • LM Studio: Check MCP server logs
   • Cursor: Check output panel
4. Reinstall Configuration
   • Remove server from config
   • Save file
   • Re-add server configuration
   • Restart client

​

Search Issues

​

No Results Found

• Search returns empty results
• "total": 0 in response

What job categories are available?
How many jobs in Poland?

​

Unexpected Results

• Results don’t match your query
• Irrelevant job offers returned

1. Be More Specific
   Copy

   ❌ "Find jobs"
   ✅ "Find Python developer jobs in Warsaw"
   
2. Use Filters
   Copy

   ❌ "IT jobs"
   ✅ "IT jobs in Poland, senior level, remote work"
   
3. Check Spelling
   • City names: “Warszawa” not “Warsaw” for Polish listings
   • Category names: Use exact names from available_categories
4. Understand Semantic Search
   • Search finds similar terms automatically
   • “CTO” also finds “Chief Technology Officer”, “Technical Director”
   • This is a feature, not a bug!

​

Configuration Problems

​

Claude Desktop Not Loading Config

• Changes to config file don’t take effect
• Old configuration still active

# 1. Quit Claude completely
killall Claude

# 2. Verify config file location
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 3. Check JSON syntax
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 4. Restart Claude
open -a Claude

​

JSON Syntax Errors

• Config file not parsed
• Client won’t start

{
  "mcpServers": {
    "hexjobs": {
      "url": "https://mcp.hexjobs.com/mcp"
    }  // Missing comma if more entries follow
    "other": {
      "url": "..."
    }
  }
}

​

Performance Issues

​

Slow Responses

• Searches take long time
• Timeouts occur

1. Reduce Result Set
   • Use smaller limit (default is 20)
   • Add more specific filters
   • Narrow down search criteria
2. Check Internet Speed
   • Test connection to server
   • Try on different network
3. Simplify Query
   • Avoid very complex multi-filter searches
   • Break into multiple simpler queries

​

Rate Limiting

• “Too many requests” errors
• Temporary blocks

• Add delays between automated requests
• Use pagination instead of multiple searches
• Cache results when possible
• Use offers_count before fetching full data

​

Data Issues

​

Missing Data Fields

• Some job offers missing salary info
• No company logo
• Incomplete descriptions

• Salary: Many companies don’t publish salary ranges
• Logos: Some companies don’t provide logos
• Descriptions: Quality varies by source

​

Outdated Listings

• Old job postings returned
• Expired positions

1. They may still be active
2. Company hasn’t set expiration date
3. Position may be evergreen (always hiring)

​

Client-Specific Issues

​

LM Studio

• Ensure LM Studio is up to date
• Try manual configuration instead
• Check LM Studio MCP documentation

​

ChatGPT Desktop

mkdir -p ~/Library/Application\ Support/OpenAI/ChatGPT

New-Item -ItemType Directory -Force -Path "$env:APPDATA\OpenAI\ChatGPT"

​

Cursor

1. Update Cursor to latest version
2. Enable Features → Model Context Protocol in settings
3. Restart Cursor

​

Cline

1. Check Cline extension is latest version
2. Reload VS Code window
3. Check VS Code output panel for errors

​

Getting Help

​

Before Contacting Support

​

Contact Support

• Client name and version (Claude Desktop 1.2.3, etc.)
• Operating system (macOS 14.0, Windows 11, etc.)
• Error messages (exact text or screenshots)
• Configuration file (remove sensitive data)
• Steps to reproduce the issue

​

Common Solutions Summary

​

Known Limitations

​

Feature Requests

• Email: contact@hexjobs.com
• GitHub: github.com/apptivitypl

• Multi-region search (implemented!)
• Semantic search (implemented!)
• Real-time webhooks (planned)
• Application tracking (planned)