Skip to main content

​
Available MCP Tools

The Hexjobs MCP server provides several tools for searching and analyzing job offers. All tools return structured JSON data and handle errors gracefully.

​
Core Search Tools

Main search tool with advanced filtering and AI-powered semantic search. Parameters:
ParameterTypeRequiredDescription
querystringNoSearch query (e.g., “python developer”, “CTO”)
countrystringNoCountry code: “PL”, “DE”, “AT”, “UA”
citiesarray[string]NoFilter by cities (e.g., [“Warszawa”, “Kraków”])
categoriesarray[string]NoJob categories (e.g., [“IT”, “Marketing”])
experience_levelsarray[string]NoExperience levels (e.g., [“junior”, “mid”, “senior”])
contract_typesarray[string]NoContract types (e.g., [“B2B”, “UoP”])
work_modesarray[string]NoWork modes (e.g., [“office”, “hybrid”, “remote”])
companiesarray[string]NoFilter by company names
is_remotebooleanNoFilter remote jobs only
min_salaryfloatNoMinimum salary threshold
limitintegerNoNumber of results (max 100, default 20)
offsetintegerNoPagination offset (default 0)
Returns: 
{
  "offers": [
    {
      "slug": "python-developer-company-123",
      "title": "Senior Python Developer",
      "company": {
        "name": "Tech Company",
        "logo": "https://..."
      },
      "location": {
        "city": "Warszawa",
        "country": "Poland"
      },
      "category": "IT",
      "experienceLevels": ["senior"],
      "contractTypes": ["B2B", "UoP"],
      "workModes": ["hybrid", "remote"],
      "salary": {
        "min": 15000,
        "max": 25000,
        "currency": "PLN"
      },
      "publishedAt": "2026-01-15T10:00:00Z",
      "url": "https://hexjobs.com/offer/python-developer-company-123"
    }
  ],
  "total": 156,
  "limit": 20,
  "offset": 0
}
Example Usage: 
Search for senior Python jobs in Warsaw with minimum salary 15000 PLN

​
offer

Get detailed information about a specific job offer. Parameters:
ParameterTypeRequiredDescription
slugstringYesJob offer slug (unique identifier)
Returns: 
{
  "slug": "python-developer-company-123",
  "title": "Senior Python Developer",
  "description": "Full job description...",
  "requirements": "Job requirements...",
  "responsibilities": "Main responsibilities...",
  "benefits": "Company benefits...",
  "company": {
    "name": "Tech Company",
    "description": "Company info...",
    "logo": "https://...",
    "website": "https://..."
  },
  "location": {
    "city": "Warszawa",
    "country": "Poland",
    "address": "Street 123",
    "isRemote": true
  },
  "salary": {
    "min": 15000,
    "max": 25000,
    "currency": "PLN"
  },
  "insights": {
    "summary": "AI-generated summary",
    "keySkills": ["Python", "Django", "PostgreSQL"],
    "suitableFor": "Experienced backend developers"
  }
}

​
offers_count

Get total count of job offers matching specified filters without returning actual offers. Parameters: Same as search tool (except limit and offset) Returns: 
{
  "count": 156,
  "query": "python developer",
  "filters": {
    "country": "PL",
    "cities": ["Warszawa"]
  }
}

​
Market Data Tools

​
available_categories

Get all available job categories with counts. Parameters: None Returns: 
{
  "categories": [
    {
      "name": "IT",
      "count": 5432
    },
    {
      "name": "Marketing",
      "count": 1234
    }
  ],
  "total": 15
}

​
available_countries

Get all available countries/regions with job counts. Parameters: None Returns: 
{
  "countries": [
    {
      "name": "PL",
      "count": 8765
    },
    {
      "name": "DE",
      "count": 3456
    }
  ],
  "total": 4
}

​
available_experience_levels

Get all available experience levels with counts. Parameters: None Returns: 
{
  "experience_levels": [
    {
      "name": "junior",
      "count": 1234
    },
    {
      "name": "mid",
      "count": 4567
    },
    {
      "name": "senior",
      "count": 2345
    }
  ],
  "total": 5
}

​
available_contract_types

Get all available contract types with counts. Parameters: None Returns: 
{
  "contract_types": [
    {
      "name": "B2B",
      "count": 4567
    },
    {
      "name": "UoP",
      "count": 3456
    }
  ],
  "total": 4
}

​
available_work_modes

Get all available work modes with counts. Parameters: None Returns: 
{
  "work_modes": [
    {
      "name": "remote",
      "count": 3456
    },
    {
      "name": "hybrid",
      "count": 4567
    },
    {
      "name": "office",
      "count": 1234
    }
  ],
  "total": 3
}

​
Best Practices

​
Efficient Searching

  1. Use specific queries - More specific queries return better results
  2. Combine filters - Use multiple filters to narrow down results
  3. Paginate large results - Use limit and offset for large result sets
  4. Check counts first - Use offers_count before fetching full results

​
Query Examples

Find Python jobs

​
Error Handling

All tools return user-friendly error messages: 
{
  "error": "Unable to process search request. Please try again or adjust your filters.",
  "offers": [],
  "total": 0
}

​
Rate Limiting

The MCP server applies standard fair-use rate limiting:
  • Maximum 100 results per request
  • Reasonable request frequency expected
  • No hard limits for normal usage

​
Tips & Tricks

Use the market data tools (available_categories, available_countries, etc.) to discover what filters are available before constructing complex queries.
The limit parameter is capped at 100 results per request. For larger datasets, use pagination with offset.
Semantic search is automatically enabled when using the search tool with a query string. It understands context and synonyms.