ati-hh-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HH_TOKEN | No | hh.ru token for all calls (stdio path; ignored in HTTP mode with MCP_API_KEYS). | |
| HH_API_BASE | No | API base URL (tests and experiments). | https://api.hh.ru |
| HH_TOOLSETS | No | Comma-separated toolsets to enable; fully replaces the default list (auth is always included). | |
| HH_UA_EMAIL | No | Contact email in the User-Agent (hh.ru requirement). | placeholder |
| HH_CLIENT_ID | No | OAuth application client id from dev.hh.ru. | |
| MCP_API_KEYS | No | Comma-separated API keys guarding the HTTP endpoint (case-sensitive). | |
| HH_RATE_LIMIT | No | Requests per minute (token bucket). | 25 |
| HH_TOKEN_STORE | No | SQLite path for OAuth token pairs (Docker: /data/tokens.sqlite3). | platform dir |
| HH_REDIRECT_URI | No | OAuth redirect URI registered at dev.hh.ru. | |
| HH_CLIENT_SECRET | No | OAuth application client secret. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
MCP server for the hh.ru API. Tools are grouped into switchable toolsets; call the dict_* tools first to resolve ids for search parameters. Errors come as structured messages with hh.ru error codes and Russian descriptions.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": false,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_meA | Get information about the current hh.ru user (GET /me). Requires an hh.ru token (HH_TOKEN env, X-HH-Token header or OAuth profile). If the token has expired, the server refreshes the OAuth pair and retries the request once. |
| auth_get_login_urlA | Get the hh.ru OAuth login URL (manual code copy flow). Returns the authorize URL and Russian instructions: open the URL,
log in on hh.ru, copy the |
| auth_exchange_codeA | Exchange an hh.ru OAuth authorization code for token pair. Use after auth_get_login_url: pass the |
| auth_statusA | Show OAuth configuration and stored token status. Reports whether OAuth client credentials are configured, whether
a token pair is stored for the current profile (the request
profile in HTTP mode, |
| auth_logoutA | Revoke the hh.ru OAuth token and delete the local profile. Calls DELETE /token on hh.ru (invalidates the token pair) and removes stored tokens. Mutation: requires confirm=True. |
| dict_dictionariesA | Get hh.ru core dictionaries: currencies, genders, vacancies statuses and other enumerations used across the API. |
| dict_areasB | Get the full tree of hh.ru regions (areas): countries, federal subjects and cities, with their numeric ids. Optional additional_case=prepositional adds a Russian prepositional-case name. |
| dict_area_countriesA | Get the list of countries known to hh.ru with their numeric ids (each country is also an area). |
| dict_areaA | Get one hh.ru region (area) by its numeric id, including nested children. Optional additional_case=prepositional adds a Russian prepositional-case name. |
| dict_industriesA | Get the tree of industries (spheres of company activity) with sub-industries and their ids. |
| dict_professional_rolesA | Get the tree of professional roles (job categories) with sub-categories and their numeric ids; role ids are used in vacancy and resume search. |
| dict_languagesA | Get the dictionary of foreign languages with their ids. |
| dict_localesB | Get the locales supported by hh.ru (vacancy interface). |
| dict_resume_localesA | Get the locales supported in hh.ru resumes. |
| dict_districtsA | Get the administrative districts of Russian cities (district ids narrow down a vacancy search within a city). |
| dict_metroA | Get metro lines and stations for all hh.ru cities that have a metro map, grouped by city with station ids. |
| dict_metro_cityB | Get metro lines and stations of a single city by area id (for example 4 = Moscow). |
| dict_skillsA | Get key skills by id (one or several; up to 50 values per request). Find skill ids with suggest_skill_set. |
| dict_educational_institutionsA | Get educational institutions by id (up to 50 values per request). Find institution ids with suggest_educational_institutions. |
| dict_facultiesC | Get the faculty list of one educational institution by its id. |
| dict_vacancy_conditionsA | Get the dictionary of paid vacancy placement conditions (branded templates, priority placement and similar options). |
| suggest_areasA | Suggest hh.ru regions (areas) by name prefix; returns matching areas with ids. area_id narrows the search to children of a given region, include_parent=true adds the parent region to the response. |
| suggest_area_leavesA | Suggest leaf regions (cities/districts without children) inside area_id by name prefix; used to pick concrete locations. |
| suggest_companiesA | Suggest registered employers (companies) by name prefix with their ids and urls. |
| suggest_educational_institutionsB | Suggest educational institutions by name prefix with their ids. |
| suggest_fields_of_studyA | Suggest fields of study (specialties) by name prefix with their ids for resume and vacancy education blocks. |
| suggest_positionsA | Suggest job positions (titles) by name prefix for resumes; returns positions with professional role ids. |
| suggest_professional_rolesB | Suggest professional roles by name prefix with their ids for vacancy and resume search. |
| suggest_resume_search_keywordA | Suggest full search phrases for resume search by a partial keyword (employer side). |
| suggest_skill_setB | Suggest key skills by name prefix with their ids; skill ids are accepted by dict_skills. |
| suggest_vacancy_positionsA | Suggest job positions (titles) by name prefix for vacancies; returns positions with professional role ids. |
| suggest_vacancy_search_keywordB | Suggest full search phrases for vacancy search by a partial keyword (applicant side). |
| search_vacanciesA | Search vacancies on hh.ru. Frequent filters (text, area, salary, currency, experience, employment, schedule, search_field, page, per_page, order_by and others) are top-level parameters. Rare or niche filters are grouped into the nested |
| get_vacancyB | Get full details of one vacancy by its numeric id, including salary, key skills, contacts and branded description. |
| similar_vacanciesC | Get vacancies similar to the given vacancy id; supports the same frequent filters as search_vacancies plus the nested advanced object for rare filters. |
| related_vacanciesC | Get other vacancies of the employer that published the given vacancy; supports frequent filters plus the nested advanced object for rare filters. |
| list_negotiationsB | List negotiations (responses and invitations) of the current user. Filter by status, vacancy or unread updates; ordered by last update (newest first) by default. The response contains collections with actions URLs used by other negotiation tools. |
| get_negotiationA | Get full information about a single negotiation (response or invitation) by its id, including messages URL and available state actions. |
| update_negotiationA | Apply a collection action (for example invite or decline) to one or more negotiations. The {id} path value and required body arguments (topic_id, message, send_sms and others) come from actions[].url and actions[].arguments of the negotiation list. Mutation: requires confirm=True. |
| move_negotiationB | Change the employer or applicant state of a negotiation by moving it to another collection (for example from response to invitation). collection_name and nid come from the actions URL of the negotiation; an optional message can be attached. Mutation: requires confirm=True. |
| list_negotiation_messagesB | List all messages of a negotiation (response or invitation) thread. Note: hh.ru considers negotiation messaging legacy and recommends chats; use with_text_only to skip service messages. |
| send_negotiation_messageB | Send a new message inside a negotiation thread. Sending is possible while the conversation is open (see the hh.ru rules for negotiations). Mutation: requires confirm=True. |
| list_collection_negotiationsC | List negotiations of the unsorted responses collection ("/response") of a vacancy with resume-like filters: area, experience, education, salary range, age and others. The same URL pattern serves other collections: replace the last path segment with the collection id from the collections list. |
| mark_negotiations_readA | Mark negotiations as read. topic_id values in the body must belong to one vacancy (up to 50 ids). Mutation: requires confirm=True. |
| request_phone_interviewA | Invite an applicant to a vacancy by resume: creates an invitation negotiation, optionally sends an email message and an SMS notification. resume_id and vacancy_id are required in the body (sent form-encoded per the vendor spec). Mutation: requires confirm=True. |
| get_negotiation_test_solutionC | Get the results of tests completed by the applicant of a negotiation (attached to the vacancy). |
| list_chatsB | List chats of the current user (applicant or employer) with pagination and filters: unread only, with text messages, by vacancy status or explicit vacancy ids. |
| get_unread_countersA | Get the number of unread chats for the current user (total and with new messages). |
| get_chat_file_conditionsA | Get conditions for files attached to chat messages: allowed formats, size limits and other constraints. |
| create_chat_file_upload_linkA | Create a one-time upload link for a chat file attachment. Upload the file with a multipart POST (field 'file') to the returned URL, then send the message with the received file_upload_id (see send_chat_message). Check get_chat_file_conditions first. Mutation: requires confirm=True. |
| create_chat_without_vacancyA | Get an existing chat or create a new one bound to a resume without a specific vacancy (resume_hash is required, an optional first_message opens the conversation). Mutation: requires confirm=True. |
| leave_chatC | Leave the given chat. Mutation: requires confirm=True. |
| mark_chat_message_readB | Mark the message as the last viewed one in the chat (updates unread counters). Mutation: requires confirm=True. |
| list_chat_messagesB | List messages of a chat, starting from start_message_id in the given order (next or prev) with a limit (default 10). |
| send_chat_messageA | Send a message to a chat: either a text message ({"text": "..."}) or a file ({"file_upload_id": "..."} from create_chat_file_upload_link). Mutation: requires confirm=True. |
| update_chat_messageB | Edit the text of your own message in a chat. Mutation: requires confirm=True. |
| delete_chat_messageA | Delete your own message from a chat. Mutation: requires confirm=True. |
| get_chat_participantsC | List participants of the chat: the applicant and employer managers involved in the conversation. |
| update_chat_participantsB | Add an employer manager to the chat (body: manager id). Mutation: requires confirm=True. |
| set_chat_write_possibilityA | Enable or disable the applicant's right to write messages in the chat (employer side; applicant_write_possibility is sent as a query parameter). Mutation: requires confirm=True. |
| get_resumeA | Get a resume by id or hash: own resume for an applicant or an accessible resume for an employer. Optional flags add contact credentials, job search status and negotiation history. |
| get_resume_phoneA | Get the phone number of a resume through hh.ru call tracking (employer side; the call is logged by hh.ru). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 62 tools
Most tools target a distinct resource+action, but with 62 tools there are several near-pairs that require careful reading: dict_areas vs suggest_areas vs suggest_area_leaves, dict_metro vs dict_metro_city, suggest_positions vs suggest_vacancy_positions vs suggest_professional_roles, and list_negotiations vs list_collection_negotiations. Descriptions do clarify the boundaries (resume-side vs vacancy-side, legacy negotiations vs chats), but an agent can still misselect without close attention.
Names follow a predictable, readable pattern of domain prefix + verb/noun (dict_*, suggest_*, auth_*, chat_*, negotiation_*), with clear verb_noun forms like get_resume, list_chats, send_chat_message, delete_chat_message. Minor deviations exist (e.g. get_me, similar_vacancies, related_vacancies lack a domain prefix, and auth_get_login_url mixes prefix and verb), but the overall scheme is coherent.
62 tools far exceeds the 3-15 sweet spot and makes the surface hard for an agent to navigate; many niche dictionary/suggest endpoints could be consolidated or lazily exposed. Each tool does map to a real hh.ru endpoint, so it is not arbitrary bloat, but the count is still excessive for practical selection.
Coverage is broad across dictionaries, OAuth, negotiations, and chats (including message CRUD, file uploads, and participant management), so core workflows are reachable. However, key lifecycle operations are missing: resumes and vacancies are read-only (no create/update/publish), and applicant-side/employer-side applicant search tools are absent, leaving notable gaps.