Workable MCP Server

The Workable MCP server provides full programmatic access to the Workable recruiting and HR platform. It covers the entire hiring lifecycle — from job management and candidate sourcing through offer approvals — as well as HR operations like employee management and time off.

How to Use

Server URL: https://mcp.workable.com/mcp
Transport: Streamable HTTP, stateless, JSON mode. No SSE, no streaming.
Authentication: The server uses OAuth2 authentication
Account selection: Every tool except get_accounts requires an account parameter. Call get_accounts first to list the Workable accounts available to the authenticated user, then pass the chosen account's subdomain as the account value on every subsequent tool call.

Dynamic discovery

The server supports OAuth dynamic discovery and Dynamic Client Registration (RFC 7591 / RFC 8414), so compatible clients can register and configure themselves automatically without manual credential setup. The following well-known metadata endpoints are available:

GET https://mcp.workable.com/.well-known/oauth-authorization-server
GET https://mcp.workable.com/.well-known/oauth-protected-resource

Table of Contents

Accounts
Jobs
Candidates
Offers
Requisitions
Pipeline & Account Config
Employees
Advanced Search
Departments
Legal Entities
Work Schedules
Events
Time Off
Time Tracking
Performance Reviews
Performance Review Cycles
What This MCP Server Enables

Accounts (1 tool)

Tool	Description
`get_accounts`	List all Workable accounts accessible to the authenticated user. Call this first — use the returned `subdomain` as the `account` parameter on every other tool

Jobs (8 tools)

Tool	Description
`get_jobs`	List jobs filtered by state (`published`, `draft`, `archived`, `closed`)
`get_job`	Get full details for a specific job by shortcode
`get_job_activities`	Get the activity log for a specific job
`get_job_application_form`	Get the application form questions for a job
`get_job_custom_attributes`	Get custom attributes configured for a job
`get_job_members`	Get team members assigned to a job
`get_job_recruiters`	Get external recruiters assigned to a job
`get_job_stages`	Get the pipeline stages configured for a job

Candidates (16 tools)

Tool	Description
`get_candidates`	List candidates for a job with filtering by stage, email, and date
`get_candidate`	Get full profile details for a specific candidate
`get_candidate_activities`	Get the activity log for a candidate (stage changes, comments, etc.)
`get_candidate_activity`	Get details for a single candidate activity
`get_candidate_offer`	Get the offer associated with a specific candidate
`get_candidate_files`	List files attached to a candidate's profile — timeline attachments (`source: "Comment"`) and offer documents (`source: "Offer"`). Each file includes `name`, `preview_url` (temporary pre-signed link), `source`, and `kind`. Does not include the resume (use `resume_url` on `get_candidate`) or form-answer files (use `answers[].file_url` on `get_candidate`)
`create_candidate`	Source a new candidate and attach them to a specific job (supports resume, social profiles, education, experience, and application answers)
`create_talent_pool_candidate`	Add a candidate to the talent pool without attaching to a specific job
`copy_candidate`	Copy a candidate to another job, keeping the original record in the source job (duplicates profile, education, experience, resume, form answers, and tags). Returns the ID and URL of the new candidate record
`relocate_candidate`	Move a candidate to another job, removing them from the source job — only one record remains. Accepts an optional target stage (defaults to the target job's starting stage). Use this to redirect a candidate to a different role, versus `copy_candidate` for considering them for multiple roles
`move_candidate`	Move a candidate to a different pipeline stage (supports requisition linking on hire)
`disqualify_candidate`	Disqualify a candidate with a reason (rejected or withdrew)
`add_comment`	Add a comment to a candidate with visibility controls
`add_review`	Add a rating/review to a candidate (thumbs, stars, or numeric scale)
`upsert_candidate_rating`	Submit or update a candidate rating with upsert semantics — updates the existing rating for the member on the stage, otherwise creates one. Preferred over `add_review` for agent workflows. Scales and grade ranges: `thumbs` (0–2), `stars` (0–4), `numbers` (0–9). `stage_id` is optional and defaults to the candidate's current stage; the rating is attributed to the authenticated member
`update_candidate_tags`	Replace the full set of tags on a candidate — the provided array overwrites all existing tags (pass `[]` to clear). To add a tag while keeping existing ones, fetch the candidate first and merge

Offers (3 tools)

Tool	Description
`get_offer`	Get details for a specific offer by ID
`approve_offer`	Approve an offer
`reject_offer`	Reject an offer with an optional rejection reason

Requisitions (6 tools)

Tool	Description
`get_requisitions`	List requisitions with filtering by state, job, and date
`get_requisition`	Get details for a specific requisition by code
`create_requisition`	Create a new headcount requisition with job title, owner, hiring manager, salary, and department
`update_requisition`	Update an existing requisition (employment type, experience, location, salary, reason, notes, plan date, hiring manager, owner). Partial updates supported — only provided fields change. Requisition code, linked job, and department cannot be modified. Updating an approved requisition returns it to pending for re-approval. Returns the full updated requisition
`approve_requisition`	Approve a requisition by code
`reject_requisition`	Reject a requisition with an optional rejection reason

Pipeline & Account Config (4 tools)

Tool	Description
`get_stages`	Get all available recruitment pipeline stages in the account
`get_members`	List account members, filterable by role, status, email, and job
`get_disqualification_reasons`	Get all configured disqualification reasons (required before disqualifying a candidate)
`get_account_custom_attributes`	Get all custom attributes configured at the account level

Employees (4 tools)

Tool	Description
`get_employees`	List employees with search, status filtering, and ordering by department or division
`get_employee`	Get full details for a specific employee
`get_employee_documents`	List documents attached to an employee's profile — each document includes its ID, file name, file type, upload date, and download URL. Respects existing Workable access permissions
`get_orgchart`	Get the organization chart, optionally scoped to a legal entity, department, or employee subtree

For multi-field employee filtering (by any standard or custom field, with column selection, sort, and pagination), see the Advanced Search section below. get_employees remains the simple option for text search by name or email.

Advanced Search (9 tools)

Beyond the basic list tools, the server exposes three parallel advanced search capabilities — for candidates, employees, and employee profile-update requests. Each supports filtering by any available field (standard or custom), column selection, sort, and pagination, and each follows the same three-step workflow:

Discover the schema — call the *_fields tool to get the available columns, field types, and search operators.
Resolve dropdown values — for dropdown/enum fields, call the *_filter_options tool with the field/filter ID to get the valid option values at query time.
Run the search — call the search_* tool with any combination of filters, column selection, sort, and pagination; only matching records are returned.

The basic list tools (get_candidates, get_employees) remain available for simple lookups.

Candidates

Tool	Description
`get_candidate_detailed_fields`	Step 1 — return the full candidate field schema: field names, types, operators, and valid options for dropdowns
`get_candidate_detailed_filter_options`	Step 2 — return the current valid values for a given dropdown field/filter ID
`search_candidates_detailed`	Step 3 — search candidates by any combination of standard and custom filters, with column selection, sort, and pagination

Employees

Tool	Description
`get_employee_fields`	Step 1 — return the full employee field schema: field names, types, operators, and valid options for dropdowns
`get_employee_filter_options`	Step 2 — return the current valid values for a given dropdown field/filter ID
`search_employees`	Step 3 — search employees by any combination of standard and custom filters, with column selection, sort, and pagination

Profile Updates

Profile updates are employee-initiated requests to change their own profile data (e.g. address, bank details, emergency contacts).

Tool	Description
`get_profile_update_fields`	Step 1 — return the available columns and filter fields for profile update requests
`get_profile_update_filter_options`	Step 2 — return the valid option values for a given dropdown field/filter ID
`search_profile_updates`	Step 3 — search profile update requests by filters, with column selection, sort, and pagination

Departments (5 tools)

Tool	Description
`get_departments`	List all departments in the account
`create_department`	Create a new department, optionally under a parent department
`update_department`	Update a department's name or parent
`delete_department`	Delete a department by id (supports `force` to delete even when the department has data)
`merge_department`	Merge a source department into a target department, moving all associated data

Legal Entities (1 tool)

Tool	Description
`get_legal_entities`	Get all legal entities configured in the account

Work Schedules (1 tool)

Tool	Description
`get_work_schedules`	Get all work schedules configured in the account

Events (2 tools)

Tool	Description
`get_events`	List events (calls, interviews, meetings) with filtering by job, candidate, member, type, and date range
`get_event`	Get full details for a specific event

Time Off (5 tools)

Tool	Description
`get_timeoff_requests`	Get time off requests within a date range, filterable by employee, category, and state
`get_timeoff_balances`	Get time off balances for a specific employee or all employees
`get_timeoff_categories`	Get all configured time off categories
`create_timeoff_request`	Create a new time off request (supports half-day entries and notes)
`update_timeoff_approval`	Approve or reject a pending approval from the `pending_approvals` array

Time Tracking (6 tools)

Tool	Description
`list_time_entries`	List time tracking entries with filters for date range, employees, type (`time-entry`, `clock-in`, `clock-out`), and duration
`create_time_entry`	Create a complete time entry (both `clock_in_time` and `clock_out_time`) for an employee
`clock_in`	Open a clock-in for an employee at the supplied UTC timestamp (`clock_in_time` is required)
`clock_out`	Close the currently open clock-in for an employee at the supplied UTC timestamp (`clock_out_time` is required); returns an array of the entries closed by this clock-out
`bulk_create_time_entries`	Create complete time entries for multiple employees in one request (max 500)
`update_time_entry`	Update an existing entry's clock-in/out times or note (pass `note: null` to clear)

📘
Time strings on time-tracking responses are ISO 8601 in UTC (with the Z suffix). Each entry includes a timezone field with the IANA timezone resolved for the timesheet — use it to render wall-clock time when needed. See the time-tracking API docs for details.

Performance Reviews (3 tools)

Tool	Description
`get_review_cycle_templates`	List performance review cycle templates (paginated)
`get_review_cycle_template`	Get a specific template by id, including its sections and questions
`create_review_cycle_template`	Create a template with sections and questions (paragraph, star / numeric / custom rated, multiple choice). Mark a question as the section-level or template-level rating by setting `metadata.semanticType` to `"section_rating"` (one per section, must be a rated type) or `"overall_rating"` (one per template, must be a rated type)

Performance Review Cycles (12 tools)

These tools drive a running review cycle end to end — discover cycles, prepare and customize questionnaires, complete and submit reviews, then share and sign the outcome. They complement the template tools above (which define reusable cycle templates). Most tools are scoped to what the authenticated member is entitled to see and do. IDs flow in this order: get_review_cycles → cycle id; list_review_tasks → aggregate (task) id and review id; use each ID with the tool that expects it.

Tool	Description
`get_review_cycles`	List performance review cycles visible to the account. Supports `limit`/`offset` pagination and a `states` filter (`draft`, `scheduled`, `in_preparation`, `active`, `ended`); archived/deleted cycles are never returned. The returned cycle `id` is the entry point for every other tool here
`get_review_cycle`	Get a single review cycle by `id`, including its dates, deadlines, counts, and configured review types (self / manager / peer / upwards)
`list_review_tasks`	List the authenticated member's review tasks in a cycle, split into `preparation_tasks` (templates to customize as aggregate manager) and `active_tasks` (each with a reviewee, the aggregate-level actions, and a `reviews[]` array). Use a review `id` with `get_review`/`submit_review` and the aggregate (task) `id` with `get_review_form`/`update_review_form`/`mark_review_task_ready`/`share_review`/`sign_review`
`get_review_form`	Fetch the questionnaire form for a given `review_type` (`self`/`manager`/`peer`/`upwards`) on a preparation task, returning the underlying review plus its sections and questions
`update_review_form`	Create or replace the questionnaire for a review type on a preparation task. The whole questionnaire is replaced (not merged) — pass the complete set of sections and questions. Question types: `paragraph`, `star_rated`, `custom_rated`, `numeric_rated`, `multiple_choice`. Rejected if the cycle disallows manager overwrite or the form is already marked ready in an active cycle
`mark_review_task_ready`	Finalize every customizable review form on a preparation task. Point of no return — once ready in an active cycle the forms can no longer be edited; confirm with the user first
`get_review`	Fetch a single review by `review_id` as `{ review, questionnaire }` — the template merged with any autosaved draft answers. Restricted to the assigned reviewer (the reviewee for self-reviews)
`submit_review`	Fill in a review and either `save` (autosave a draft, upserting answers by `question_id`) or `submit` (run validation and finalize). Submit is final — a second submit fails; confirm with the user before submitting
`share_review`	Share a completed review aggregate with the reviewee and send notifications. Takes the aggregate (task) `id`, not a review ID; the manager review must be submitted first
`sign_review`	Record the calling member's signature on a shared review aggregate (reviewee and/or manager). Takes the aggregate (task) `id`. Signing is final; confirm with the user first
`get_review_aggregate`	Fetch an employee's full review aggregate in a cycle — status, reviewee, manager, cycle, and every review visible to the caller (each as `{ review, questionnaire }`). Peer/upward reviewers see only their own assigned review
`list_review_cycle_answers`	Bulk-pull every persisted answer in a cycle for reporting integrations. Requires admin `ReviewCyclesView` permission. Submitted answers only by default; `include_drafts=true` adds drafts. Filter by `question_ids`, `review_types`, `employee_ids`; paginate with `limit` (1–200, default 50)/`offset`. Anonymous reviewers report as `{ id: null, name: "Anonymous" }`

What This MCP Server Enables

The Workable MCP server bridges AI assistants directly with the Workable platform, enabling:

End-to-end recruiting automation — search jobs, source candidates, copy or relocate them across jobs, move them through the pipeline, rate and review them, retrieve their files, and manage offers without leaving your AI interface
HR self-service — look up employees, retrieve their documents, explore the org chart, check time off balances, and create or approve leave requests conversationally
Advanced search — filter candidates, employees, and profile-update requests by any standard or custom field using the three-step discover-fields → resolve-options → search workflow
Org structure management — maintain departments and legal entities, and consult work schedules when onboarding
Time tracking operations — list, create, bulk-create, and update time entries for employees
Performance management — manage review cycle templates and run entire review cycles: prepare and customize questionnaires, complete and submit reviews, then share and sign outcomes, and bulk-export answers for reporting
Requisition workflows — create, approve, or reject headcount requests programmatically
Multi-account support — operate across multiple Workable accounts from a single integration
Audit & reporting — retrieve activity logs for both jobs and candidates to understand hiring progress

Time strings on time-tracking responses are ISO 8601 in UTC (with the Z suffix). Each entry includes a timezone field with the IANA timezone resolved for the timesheet — use it to render wall-clock time when needed. See the time-tracking API docs for details.

Time strings on time-tracking responses are ISO 8601 in UTC (with the `Z` suffix). Each entry includes a `timezone` field with the IANA timezone resolved for the timesheet — use it to render wall-clock time when needed. See the time-tracking API docs for details.