> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mokaru.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tools
> Reference for every Mokaru MCP tool an AI agent can call
## Overview
The Mokaru MCP server exposes 70 tools. Each one wraps a single REST API endpoint, so behaviour, rate limits, and error responses match the [REST API](/api-reference/introduction) exactly.
Tool descriptions in this reference match what the AI agent sees via `tools/list`. AI agents pick which tool to call based on these descriptions - they're written for LLM consumption.
## Jobs
### `mokaru_search_jobs`
Search the Mokaru job database (refreshed daily). Returns listings with title, company, location, salary, and apply URL. Use cursor pagination to fetch more pages.
| Parameter | Type | Required | Description |
| ------------------ | ---------------------------------------------------- | -------- | ------------------------------------------------- |
| `query` | string | yes | Job search keywords |
| `location` | string | no | City, state, or country |
| `workArrangement` | "remote" \| "hybrid" \| "onsite" | no | Filter by work arrangement |
| `employmentType` | "FULLTIME" \| "PARTTIME" \| "CONTRACTOR" \| "INTERN" | no | Filter by employment type |
| `datePosted` | "day" \| "3days" \| "week" \| "month" | no | How recent the posting should be |
| `excludeCompanies` | string\[] | no | Company names to exclude |
| `excludeKeywords` | string\[] | no | Keywords to exclude from title/description |
| `cursor` | string | no | Pagination cursor from previous page's `postedAt` |
Underlying endpoint: `POST /v1/jobs/search`.
## Applications
### `mokaru_list_applications`
List the user's job applications. Returns id, title, company, status, and dates.
| Parameter | Type | Description |
| --------- | -------------- | ----------------------------------------------------------------- |
| `status` | enum | Filter by status (watchlist, applied, interview\_scheduled, etc.) |
| `limit` | number (1-100) | Results per page (default 25) |
| `offset` | number | Pagination offset |
### `mokaru_get_application`
Get full details for one application, including timeline events, interviews, and notes. After `mokaru_tailor_resume`, poll this tool and watch `processingStatus` (`pending` / `processing` / `completed` / `failed`) to know when the tailored resume is ready; `processingError` holds the reason on failure.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------- |
| `id` | string | yes | Application id from `mokaru_list_applications` |
### `mokaru_tailor_resume`
**The auto-prep feature.** The tool to use whenever the user wants a resume made or tailored **for a specific job**. Duplicates the user's default (base) resume and AI-tailors the copy to the job (keyword optimization, rephrased experience bullets, focused summary). Do **not** hand-build a resume with `mokaru_create_resume` for this - that bypasses the real tailoring engine. Because a tailored resume is owned by a tracker application, this also adds the job to the tracker.
Runs asynchronously (\~30s). The response returns immediately with the new `cvId` and `processingStatus: "pending"`. Poll `mokaru_get_application` with the returned `id` until `processingStatus` is `completed`, then fetch/export the resume by its `cvId`.
Requirements: Plus plan (else `PLAN_REQUIRED`), a default resume (else `NO_DEFAULT_RESUME`), and a job description >= 500 chars (else `JOB_DESCRIPTION_TOO_SHORT`). Costs 1 AI credit (unlimited on Plus).
| Parameter | Type | Required | Description |
| ---------------- | ------ | ----------- | --------------------------------------------------------------------------------------- |
| `jobTitle` | string | yes | Target job title (max 200) |
| `company` | string | yes | Hiring company name (max 200) |
| `jobDescription` | string | conditional | Full posting text (>= 500 chars). Optional when `jobListingId` has a stored description |
| `jobListingId` | string | no | ID from `mokaru_search_jobs` - hydrates the description and salary server-side |
| `location` | string | no | Job location (max 200) |
| `jobUrl` | string | no | URL to the job posting (used for de-duplication) |
| `source` | enum | no | LinkedIn, CompanyWebsite, JobWebsite, Referral, Agency, Other |
### `mokaru_create_application`
Save a job to Mokaru's tracker. Pass `autoPrepare: true` to also AI-tailor a resume in the same step (same engine as `mokaru_tailor_resume`). If the user's intent is primarily to get a tailored resume rather than to track the application, prefer `mokaru_tailor_resume`.
| Parameter | Type | Required | Description |
| ---------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `jobTitle` | string | yes | Job title (max 200) |
| `company` | string | yes | Company name (max 200) |
| `location` | string | no | Job location (max 200) |
| `jobUrl` | string | no | URL to the job posting |
| `jobDescription` | string | conditional | Full description (>= 500 chars required for `autoPrepare`) |
| `jobListingId` | string | no | ID from `mokaru_search_jobs` (links salary data) |
| `source` | enum | no | LinkedIn, CompanyWebsite, JobWebsite, Referral, Agency, Other |
| `autoPrepare` | boolean | no | When true, duplicates default resume and queues AI tailoring (\~30s). Returns `cvId` + `processingStatus` |
### `mokaru_update_application`
Update an application: change status, edit notes, adjust priority. Status change creates a timeline entry.
| Parameter | Type | Description |
| --------------------------------- | ------------ | --------------- |
| `id` | string | Application id |
| `status` | enum | New status |
| `priority` | number (1-5) | Priority level |
| `notes` | string | Free-text notes |
| `jobTitle`, `company`, `location` | string | Edit metadata |
### `mokaru_delete_application`
Soft-delete an application (recoverable via support). Confirm with the user before calling.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------- |
| `id` | string | yes | Application id |
## Resumes
### `mokaru_list_resumes`
List the user's resumes (id, name, template, default flag, timestamps).
### `mokaru_get_resume`
Get full resume content for one resume - `cvData`, `designSettings`, `sectionOrder`, and metadata.
### `mokaru_create_resume`
Create a new resume. Only `name` is required. The new resume starts as a copy of the user's **base (default) resume** content - experiences, education, skills, certificates, projects, awards, publications and interests - as an independent snapshot; editing the base afterwards doesn't change this resume. To hide some of those on this CV pass `hiddenItems`; to customise personal info per-CV pass `personalOverrides`; to reorder items within a section pass `itemOrder`.
| Parameter | Type | Required | Description |
| ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | yes | Resume name shown in the dashboard |
| `jobTitle` | string \| null | no | CV-level job title shown in the header. Overrides the profile job title for this CV |
| `template` | string | no | Template slug (e.g. "classic", "modern") |
| `isDefault` | boolean | no | Mark as the default resume |
| `cvData` | object | no | CV-level overrides for personal info / `summary`. Section arrays (`experiences`, `education`, `skills`, etc.) are silently dropped - use `hiddenItems` for visibility and the per-section MCP tools for data |
| `hiddenItems` | object | no | Map of section -> array of the resume's item IDs (from the per-section `list_*` tools - `mokaru_get_profile` returns content without item IDs) to hide on this CV. Keys: `experiences`, `education`, `skills`, `certificates`, `projects`, `awards`, `publications`, `interests`, or `customSection:` |
| `personalOverrides` | object | no | Per-CV personal-info overrides (`firstName`, `lastName`, `email`, `phone`, `address`, `jobTitle`, `seniority`, `summary`, `website`, `linkedin`, `portfolio`, `birthDate`, `driverLicense`, `profilePhoto`). Each key overrides the profile value for this CV only; null clears that key |
| `itemOrder` | object | no | Per-section ordering. Keys are section names (`experiences`, `education`, `skills`, ..., `skillCategories`); values are arrays of the resume's item IDs in the desired order. Items not listed fall back to the resume's default order |
| `selectedSummaryId` | string \| null | no | ID of the summary to render on this CV (from `mokaru_list_summaries`). Null = no summary |
| `designSettings` | object | no | Visual styling (colors, fonts, spacing, margins) |
| `optionalFields` | object | no | Show/hide toggles for optional personal fields (phone, address, birthDate, photo, etc.) |
| `sectionOrder` | array | no | Order of CV sections (e.g. `["summary", "experiences", "education", "skills"]`) |
### `mokaru_update_resume`
Update a resume. Only provided fields are modified. To toggle which of this resume's items show on the CV, set `hiddenItems` (replaces the existing value; pass `null` to clear). Same null-to-clear semantics for `personalOverrides`, `itemOrder`, `selectedSummaryId`, and `jobTitle`.
| Parameter | Type | Required | Description |
| ------------------- | -------------- | -------- | --------------------------------------------------------------------- |
| `id` | string | yes | Resume id |
| `name` | string | no | New name |
| `jobTitle` | string \| null | no | CV-level job title (or null to clear) |
| `template` | string | no | Template slug |
| `isDefault` | boolean | no | Mark/unmark as default |
| `cvData` | object | no | CV-level overrides (section arrays ignored, see create) |
| `designSettings` | object | no | Visual styling |
| `optionalFields` | object | no | Show/hide toggles for optional personal fields |
| `sectionOrder` | array | no | Order of CV sections |
| `hiddenItems` | object \| null | no | Per-section blacklist (see create). Pass `null` to clear |
| `personalOverrides` | object \| null | no | Per-CV personal-info overrides (see create). Pass `null` to clear all |
| `itemOrder` | object \| null | no | Per-section ordering (see create). Pass `null` to clear |
| `selectedSummaryId` | string \| null | no | Summary id to use, or null |
### `mokaru_duplicate_resume`
Duplicate an existing resume. Copies every CV-level setting (template, design, hidden items, personal overrides, item order, etc.) into a new resume. The duplicate is never the default. The duplicate gets its own independent copy of the source's content (experiences, skills, etc.) - editing one doesn't affect the other.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `id` | string | yes | Source resume id |
| `name` | string | no | Name for the new copy (default ` - copy`) |
### `mokaru_delete_resume`
Delete a resume permanently. If the default is deleted, another resume is auto-promoted to default. Unlinks from any linked applications. Cannot be undone - confirm with the user.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id` | string | yes | Resume id |
### `mokaru_export_resume_pdf`
Returns a **deep-link** that opens the resume in the Mokaru web app with the Export section already active. The user clicks the link, signs in to Mokaru if needed (usually already signed in via the same browser as Claude.ai), and downloads through the standard Export PDF button.
The URL pattern is `{appBaseUrl}/{locale}/resumes/builder?cvId={id}&tab=export` - for example `https://app.mokaru.ai/en/resumes/builder?cvId=clx...&tab=export`.
**Why a link instead of an inline file?** The MCP web client (claude.ai) currently cannot reliably render binary content blocks (PDFs in particular) as downloads - it rejects them as un-renderable images. Returning a link works in every MCP client (Claude.ai web, Claude Desktop, Cursor, Gemini CLI, custom agents). Direct inline PDF download via MCP is on the roadmap and will ship once client support stabilises.
| Parameter | Type | Required | Description |
| --------- | ------------ | -------- | -------------------------------------------- |
| `id` | string | yes | Resume id to open in the export view |
| `locale` | "en" \| "nl" | no | Locale segment used in the URL (default: en) |
## Profile
### `mokaru_get_profile`
Get the user's career profile in one call. Returns scalar fields (name, contact, summary, sector, links) PLUS the base (default) resume's content collections (the canonical content that new resumes are copied from):
* `skills`, `workExperiences`, `educations`
* `summaries` (professional summary versions)
* `projects`
* `certificates`
* `awards`
* `publications`
* `interests`
* `jobTitles` (career-identity titles)
* `customSections` (with their items inline)
One call returns the entire profile - no need to fetch each section separately.
`mokaru_get_profile` returns content **without item IDs**. To get the IDs needed for `mokaru_update_*` / `mokaru_delete_*` or for a resume's `hiddenItems` / `itemOrder`, use the per-section `list_*` tools - they are the canonical ID source.
### `mokaru_update_profile`
Update profile **scalars** (name, contact, summary, etc.) and several of the base (default) resume's content collections in bulk. For granular edits prefer the per-section CRUD tools described below (`mokaru_create/update/delete_experience`, `_education`, `_skill`, etc.) - they target one row at a time and never clobber other items.
This tool still supports **replace-list** writes for `summaries`, `projects`, `certificates`, `awards`, `publications`, `interests`, `jobTitles`: passing an array REPLACES the entire collection. The pattern to add one item is fetch → append → send the full array back.
`workExperiences`, `educations` and `skills` cannot be written here - use the dedicated per-item tools.
| Parameter | Type | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstName`, `lastName`, `email`, `phone`, `address`, `country`, `province`, `jobTitle`, `summary`, `sector`, `linkedIn`, `website`, `portfolio` | string | Scalar fields (pass null to clear) |
| `summaries` | array (max 100) | Replace-list of summaries |
| `projects` | array (max 100) | Replace-list of projects |
| `certificates` | array (max 100) | Replace-list of certificates |
| `awards` | array (max 100) | Replace-list of awards |
| `publications` | array (max 100) | Replace-list of publications |
| `interests` | array (max 100) | Replace-list of interests |
| `jobTitles` | array (max 50) | **Legacy** - job titles now live per-resume on `EmpCV.jobTitle` (set via `mokaru_create_resume` / `mokaru_update_resume`). Kept for backwards compatibility |
## Profile sections (per-item CRUD)
Each profile section exposes a 4-tool shape: `list_*`, `create_*`, `update_*`, `delete_*`. These are the **preferred** way to mutate individual items; they avoid the replace-list footgun of `mokaru_update_profile`. (There is no per-item `get_*` - `list_*` already returns every item with its full fields and ID, so a single-item fetch would add nothing.)
**Targeting a specific resume (`cvId`).** Every per-section tool (and the custom-section item tools) accepts an optional `cvId`. Omit it and the tool reads/writes your **base (default) resume**'s content. Pass a resume id (from `mokaru_list_resumes`) to target that specific resume instead - e.g. rewrite a bullet on a tailored CV. Call `list_*` with the same `cvId` first to get that resume's item IDs, then `update_*` / `delete_*` with the matching `cvId`. The resume must belong to you and be self-contained (a non-self-contained/legacy resume returns 400; an unknown or unowned id returns 404).
The tool inputs mirror the underlying v1 REST endpoint schema (see API Reference per section for the exact field list). The behaviour is identical: only provided fields change, pass `null` on a nullable field in update to clear it.
| Section | Tools | v1 endpoint |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Work experiences | `mokaru_list_experiences`, `_create_experience`, `_update_experience`, `_delete_experience` | `/v1/experiences` |
| Education | `mokaru_list_education`, `_create_education`, `_update_education`, `_delete_education` | `/v1/education` |
| Skills | `mokaru_list_skills`, `_create_skill`, `_update_skill`, `_delete_skill` | `/v1/skills` |
| Certificates | `mokaru_list_certificates`, `_create_certificate`, `_update_certificate`, `_delete_certificate` | `/v1/certificates` |
| Projects | `mokaru_list_projects`, `_create_project`, `_update_project`, `_delete_project` | `/v1/projects` |
| Awards | `mokaru_list_awards`, `_create_award`, `_update_award`, `_delete_award` | `/v1/awards` |
| Publications | `mokaru_list_publications`, `_create_publication`, `_update_publication`, `_delete_publication` | `/v1/publications` |
| Interests | `mokaru_list_interests`, `_create_interest`, `_update_interest`, `_delete_interest` | `/v1/interests` |
| Summaries | `mokaru_list_summaries`, `_create_summary`, `_update_summary`, `_delete_summary` | `/v1/summaries` |
| Custom sections (definition) | `mokaru_list_custom_sections`, `_create_custom_section`, `_update_custom_section`, `_delete_custom_section` | `/v1/custom-sections` |
| Custom section items | `mokaru_create_custom_section_item`, `_update_custom_section_item`, `_delete_custom_section_item` | `/v1/custom-sections/{id}/items`, `/v1/custom-section-items/{id}` |
Common idioms:
* **Add a single item** without touching the rest: `mokaru_create_`. No need to fetch the existing list first.
* **Edit one field** on an existing item: `mokaru_update_` with `{ id, : }`. Other fields stay untouched.
* **Hide one of a resume's items on that CV** (without deleting it): use `mokaru_update_resume` with `hiddenItems`, not the delete tool.
* **Select which summary appears on a CV**: `mokaru_create_summary` to add the variant, then `mokaru_update_resume` with `selectedSummaryId` set to that summary's id.
## Resume sharing (public links)
### `mokaru_create_resume_share`
Create a public share link for a resume. Snapshots the resume's current `cvData`, design settings, section order and optional fields into a `EmpResumeShare` row so the shared page renders the state at share-creation time, independent of later edits. If a share already exists for this resume, the existing link is returned (upsert).
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `resumeId` | string | yes | Resume to share |
| `blurOptions` | object | no | Privacy toggles: `blurLinkedIn`, `blurWebsite`, `blurPortfolio`, `blurCompanies`, `blurInstitutions` (each a boolean) |
Returns `{ success, shareId, shareUrl, createdAt, reused }`. The public URL pattern is `https://app.mokaru.ai/share/{shareId}`.
### `mokaru_list_resume_shares`
List the share links for a resume. Returns each share with its public URL.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `resumeId` | string | yes | Resume id |
### `mokaru_delete_resume_share`
Revoke a public share link. The public viewer at `/share/{shareId}` 404s immediately after.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `shareId` | string | yes | Share id |
## Cover letters
**Plus plan only** for `create` and `update`. Returns `403` with `{ requiresUpgrade: true }` if the user is on the free plan. `list`, `get` and `delete` are available on any plan so users can still see and clean up their existing cover letters after downgrading.
A cover letter is always linked one-to-one to a resume (`cvId` is required and unique). To "add a cover letter to a resume" first check whether one exists via `mokaru_list_cover_letters` with `cvId`; if it does, call `mokaru_update_cover_letter`; if not, call `mokaru_create_cover_letter`. Create returns `409` if a cover letter already exists for that resume.
If the user has no resume yet, you can't create a cover letter at all - first call `mokaru_list_resumes`; if empty call `mokaru_create_resume` to make one, then use its id as `cvId`.
### `mokaru_list_cover_letters`
List the user's cover letters.
| Parameter | Type | Description |
| ----------------- | ------ | ----------------------------------------- |
| `cvId` | string | Filter to the cover letter for one resume |
| `limit`, `offset` | number | Pagination |
### `mokaru_get_cover_letter`
Get the full content of one cover letter (title, body, variables, styling).
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------- |
| `id` | string | yes | Cover letter id |
### `mokaru_create_cover_letter`
Create a cover letter for a resume.
| Parameter | Type | Required | Description |
| --------------------------------------------------- | ------------------------- | -------- | ------------------------------------------------------------------------ |
| `cvId` | string | yes | Resume to attach to (must be owned by the caller; unique) |
| `title` | string | yes | Cover letter title (max 200) |
| `content` | string | yes | Body text (markdown allowed) |
| `templateId` | string \| null | no | Optional cover letter template id |
| `isDefault` | boolean | no | Mark as user's default cover letter |
| `variables` | object | no | Template-variable map, e.g. `{ company: "Acme", contactPerson: "Jane" }` |
| `showName`, `showEmail`, `showPhone`, `showAddress` | boolean | no | Header visibility toggles |
| `headerAlignment` | `left \| center \| right` | no | Header alignment |
| `fontFamily` | string | no | Font family (default `Inter`) |
| `fontSize` | number | no | Font size in pt (default 11) |
| `lineSpacing` | number | no | Line spacing (default 1.6) |
### `mokaru_update_cover_letter`
Update a cover letter. Only provided fields are modified. Pass `null` on nullable fields to clear.
| Parameter | Type | Description |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------ |
| `id` | string | Cover letter id |
| `title`, `content`, `templateId`, `isDefault`, `variables`, `showName`, `showEmail`, `showPhone`, `showAddress`, `headerAlignment`, `fontFamily`, `fontSize`, `lineSpacing` | various | Same shape as `mokaru_create_cover_letter` |
### `mokaru_delete_cover_letter`
Permanently delete a cover letter. The parent resume is unaffected.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------- |
| `id` | string | yes | Cover letter id |
## Contacts
### `mokaru_list_contacts`
List professional contacts (recruiters, hiring managers, colleagues, etc.).
| Parameter | Type | Description |
| -------------- | -------------- | --------------------------------- |
| `relationship` | enum | Filter by relationship type |
| `search` | string | Search by name, company, or email |
| `limit` | number (1-100) | Results per page |
| `offset` | number | Pagination offset |
### `mokaru_create_contact`
Create a new contact.
| Parameter | Type | Required | Description |
| ---------------------------- | ------ | -------- | -------------------------------- |
| `firstName`, `lastName` | string | yes | Contact name |
| `jobTitle`, `company` | string | no | Role and company |
| `relationship` | enum | no | RECRUITER, HIRING\_MANAGER, etc. |
| `email`, `phone`, `linkedIn` | string | no | Contact details |
### `mokaru_update_contact`
Update a contact. Only provided fields are modified. Pass `null` to clear a field.
| Parameter | Type | Description |
| -------------------------------------------------------------------------------------------- | ------ | --------------- |
| `id` | string | Contact id |
| `firstName`, `lastName`, `jobTitle`, `company`, `relationship`, `email`, `phone`, `linkedIn` | string | Editable fields |
### `mokaru_delete_contact`
Permanently delete a contact. Cannot be undone - confirm with the user.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id` | string | yes | Contact id |
## Error handling
Every tool returns errors as MCP error content blocks (`isError: true` with a text explanation). Errors map from the underlying REST API:
| HTTP | MCP tool message |
| ---- | ----------------------------------------------------------------- |
| 400 | `Invalid request.` |
| 401 | `Your MCP session has expired. Please re-authorize Mokaru.` |
| 403 | `Permission denied. This action requires: {scopes}` |
| 404 | `Not found.` |
| 409 | `Resource is currently being processed - retry in a few seconds.` |
| 429 | `Rate limited. Retry after {seconds}s.` |
| 5xx | `Mokaru API error ({status}). Try again later.` |
Unexpected internal tool errors are returned as a generic failure message while detailed diagnostics stay in server logs.