Query the Recruiter Roles job board from any MCP-capable AI client (Claude, Cursor, ChatGPT, VS Code, …). Ask in plain language and get live recruiter and talent-acquisition jobs, company profiles, sectors, locations, and market stats — straight from the board.
Read-only. Authenticated with a free Recruiter Roles API key.
Hosted (recommended): https://recruiterroles.com/api/mcp (Streamable HTTP)
Local (this package): npx recruiter-roles-mcp (stdio, for stdio-only clients)
Get a free API key: https://recruiterroles.com/api-access
Docs: https://recruiterroles.com/mcp · REST API: https://recruiterroles.com/api-docs
Tool | Description |
| Search & filter live jobs (sector, location, salary, remote, recency, full-text). |
| Full detail for one job — description, requirements, benefits, apply contact. |
| Browse recruiting agencies & employers with active job counts. |
| A company profile plus its active jobs. |
| All recruiting sectors with live job counts. |
| Countries, regions, and cities with live job counts. |
| Aggregate market overview — totals, posting velocity, and breakdowns. |
All tools are annotated readOnlyHint: true, destructiveHint: false,
openWorldHint: false, and expose an outputSchema.
Related MCP server: JobsPipe MCP Server
Most clients can connect directly to the hosted Streamable HTTP endpoint with
your API key in the Authorization header (or as a ?key= query param for
clients that can't set headers).
Cursor — ~/.cursor/mcp.json:
{
"mcpServers": {
"recruiter-roles": {
"url": "https://recruiterroles.com/api/mcp",
"headers": { "Authorization": "Bearer rr_live_YOUR_KEY" }
}
}
}VS Code — .vscode/mcp.json:
{
"servers": {
"recruiter-roles": {
"type": "http",
"url": "https://recruiterroles.com/api/mcp",
"headers": { "Authorization": "Bearer rr_live_YOUR_KEY" }
}
}
}Claude / ChatGPT custom connector — add the URL with your key appended:
https://recruiterroles.com/api/mcp?key=rr_live_YOUR_KEYFor stdio-only clients or local development. Set your API key via the
RECRUITER_ROLES_API_KEY environment variable:
{
"mcpServers": {
"recruiter-roles": {
"command": "npx",
"args": ["-y", "recruiter-roles-mcp"],
"env": { "RECRUITER_ROLES_API_KEY": "rr_live_YOUR_KEY" }
}
}
}Run it directly:
RECRUITER_ROLES_API_KEY=rr_live_YOUR_KEY npx recruiter-roles-mcpThis is a thin, read-only layer over the public Recruiter Roles
v1 REST API. Each tool forwards your API
key to one GET /api/v1/* endpoint, so MCP usage shares the same rate limit
(1,000 requests/day per key), caching, and request logging as the REST API. The
server holds no database connection and no secrets of its own.
npm install
npm run build
RECRUITER_ROLES_API_KEY=rr_live_YOUR_KEY node dist/index.jsOptional: point at a different origin during development with
RECRUITER_ROLES_BASE_URL (default https://recruiterroles.com).
Any page or product that publishes data obtained through this server must include a visible, crawlable link back to Recruiter Roles. Keys may be suspended if the backlink is removed.
MIT — see LICENSE.
Fetch a single company's full profile plus a paginated list of its active jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The company slug (e.g. 'robert-half'). | |
| page | No | Page of the company's jobs. Default: 1. | |
| per_page | No | Jobs per page. Default: 20, max: 100. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds valuable context by specifying it returns 'active jobs' (not all jobs), which goes beyond the annotations and aligns with the read-only, idempotent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and front-loaded. It could be slightly more concise but is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the clear statement of what is returned (profile + paginated jobs), the description is fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description does not add additional meaning beyond what the schema provides for slug, page, and per_page. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'single company's full profile', and the additional return of 'paginated list of its active jobs'. This distinguishes it from siblings like get_job (single job) and list_companies (list of companies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It is adequate but lacks exclusions or context like 'use list_companies to browse all companies'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full detail for a single job by its slug, including the complete description, requirements, benefits, tech stack, and apply contact.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The job slug (the last path segment of its URL, or the 'slug' field from search_jobs). |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it returns specific fields, which is useful context but does not reveal additional behavioral traits beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the main action and includes details on what is returned. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 parameter, has output schema, comprehensive annotations), the description fully covers what the tool does and what it returns. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already provides a detailed description of the 'slug' parameter. The tool description mentions 'by its slug' but adds no new meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool fetches full detail for a single job by slug, and lists included fields (description, requirements, benefits, tech stack, apply contact). This distinguishes it from siblings like search_jobs which returns summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when you need full job details given a slug, implying slug is obtained from search_jobs. Lacks explicit when-not or alternative references, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse the directory of recruiting companies and agencies with their active job counts. Filter by name, company type, or HQ country.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search company name. | |
| company_type | No | Company type filter. | |
| country | No | HQ country code (e.g. 'US', 'GB'). | |
| sort | No | Sort order. Default: job_count. | |
| page | No | Page number. Default: 1. | |
| per_page | No | Results per page. Default: 20, max: 100. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes | |
| response_generated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context that the tool returns active job counts and supports filtering, which is behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the core purpose, followed by filtering details. No wasted words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 6 optional parameters and an output schema, the description covers the main action and return data (active job counts). Pagination and sorting are not mentioned but are detailed in the schema, so completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions filtering by name, type, and country, which aligns with schema but adds no additional meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'browse' and resource 'directory of recruiting companies', with specific details on returned data (active job counts) and filtering options. Distinguishes from siblings like get_company (single entity) and search_jobs (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage to list and filter companies, but no explicit guidance on when to use this tool versus alternatives (e.g., get_company for a specific company). Context signals provide sibling names but the description does not contrast them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the location hierarchy (countries, regions, or cities) with active job counts. Use the returned codes/slugs for the 'state' and 'city' filters in search_jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Hierarchy level to return. Default: countries. | |
| country | No | Filter by country code (e.g. 'US', 'GB'). | |
| region | No | Filter cities by region code (e.g. 'TX'). Use with level=cities. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| response_generated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark tool as read-only and idempotent. Description adds that it returns active job counts, which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words, front-loaded with key purpose and usage instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All parameters explained in schema, output schema exists, description covers purpose and usage completely for its scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions (100% coverage). Description mentions job counts (return value) but doesn't add parameter semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists location hierarchy (countries, regions, cities) with active job counts, and distinguishes from sibling tools like list_companies and list_sectors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use returned codes/slugs for 'state' and 'city' filters in search_jobs, providing clear context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all recruiting sectors with their current active job counts. Use the returned slugs for the 'sector' filter in search_jobs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| response_generated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds value by disclosing that the tool returns current active job counts and that slugs are used for filtering, beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no superfluous information. Front-loaded with the core action and immediately useful context about output usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no parameters, the description fully covers the tool's functionality. Output schema exists, so return value details are not needed. Schema description coverage is 100%.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description correctly avoids parameter details. Baseline 4 applies per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'sectors' with additional detail about returning active job counts. It differentiates from sibling tools by specifying the output includes slugs for filtering in search_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use returned slugs for the 'sector' filter in search_jobs, providing clear context. No exclusions or alternatives needed as this is a simple enumeration tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate market overview: total active jobs, posting velocity (24h / 7d), and breakdowns by sector, employment type, work arrangement, and country.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| response_generated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds useful behavioral context about the aggregate nature and included breakdowns, but doesn't discuss rate limits or other traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key phrase 'Aggregate market overview'. No redundancy, every part adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema (not shown), description adequately explains the tool's return data. Could mention time ranges or update frequency, but sufficient for complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no parameters; schema coverage is vacuous (100%). Description adds value by explaining the output fields and metrics, compensating for the lack of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides an aggregate market overview with specific metrics (total active jobs, posting velocity, breakdowns). It distinguishes from siblings like get_company or search_jobs which focus on individual entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for high-level market stats but does not explicitly say when to use this tool vs alternatives like search_jobs for specific listings. No exclusions or when-not guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search live recruiter and talent-acquisition job listings on Recruiter Roles. Supports full-text search and filtering by sector, location, employment type, work arrangement, salary, and recency. Returns a paginated list with salary, company, location, and a tracked apply URL.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Full-text search across job title and company name. | |
| sector | No | Sector slug, comma-separated for multiple (e.g. 'technology,financial-services'). Use list_sectors for valid slugs. | |
| state | No | State/region code, comma-separated (e.g. 'TX,NY,BC'). Use list_locations for codes. | |
| city | No | City slug, comma-separated (e.g. 'dallas-tx'). | |
| employment_type | No | Employment type filter. | |
| work_arrangement | No | Work arrangement filter. | |
| is_remote | No | Shorthand for work_arrangement=remote. | |
| salary_min | No | Minimum salary in USD. Only returns jobs with a disclosed salary at or above this. | |
| salary_disclosed | No | true = only jobs with a disclosed salary; false = only undisclosed. | |
| source_type | No | 'direct' = employer-posted, 'scraped' = aggregated. | |
| posted_since | No | ISO date — jobs posted on or after this date. | |
| updated_since | No | ISO datetime — for incremental sync; jobs updated on or after this. | |
| sort | No | Sort order. Default: recent. | |
| page | No | Page number. Default: 1. | |
| per_page | No | Results per page. Default: 20, max: 100. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| meta | Yes | |
| response_generated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it returns a 'paginated list with salary, company, location, and a tracked apply URL,' providing some behavioral context beyond annotations. However, it does not discuss rate limits, caching, or other nuances that could be important.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences. The first sentence defines the core purpose, and the second lists key features and return fields. No extraneous information. Perfectly front-loaded and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (15 parameters, rich schema, output schema present), the description adequately covers the tool's scope and what it returns. It mentions pagination and key fields. Minor omission: default sort order and pagination details are only in the schema, but the description is still complete enough for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, all 15 parameters are already well-documented in the input schema. The description provides a high-level summary of filtering capabilities but does not add significant new meaning or examples beyond what the schema offers. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search live recruiter and talent-acquisition job listings on Recruiter Roles.' It specifies the resource (job listings), the action (search), and the context (recruiter and talent-acquisition). This distinguishes it from sibling tools like get_company or get_job, which target individual entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by listing supported filters (sector, location, etc.) and return fields, but it does not explicitly state when to use this tool versus alternatives like list_companies or get_job. No when-not guidance is provided. The context is clear enough for a basic understanding, but explicit alternatives are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clear, distinct purpose: get_company and get_job retrieve single entities, list_* tools browse catalogs, market_stats provides aggregate data, and search_jobs handles search. There is no functional overlap.
All tool names use lowercase with underscores, follow a consistent pattern (get_ for single items, list_ for browsing, search_ for search, and a descriptive noun for market stats). No mixed conventions.
Seven tools are well-scoped for a job board and salary reports domain, covering browsing, searching, and market statistics without being too few or excessive.
The tool set covers core CRUD-like operations (listing, reading, searching) and market aggregation. A dedicated salary report tool is missing, but salary data is accessible via search and market_stats, so gaps are minor.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search 490k+ live jobs from company ATS boards, save roles, follow companies, manage talent profile.
Search a live index of millions of open jobs from employer career sites and 100+ ATS platforms.
AI sales & BD platform for Australian recruiters: search, enrich, campaign, research, reports.
Search 10k+ live cybersecurity jobs from 246 security companies, plus salary benchmarks and stats.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/pcmarts/recruiter-roles-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
