Skip to main content

​
MCP Server

Nico exposes a Model Context Protocol (MCP) server that allows AI assistants like Claude to interact with your job applications directly.

​
What can the MCP server do?

The MCP server provides 6 tools:
ToolTypeDescription
list_job_applicationsReadList your job applications with filtering
search_job_applicationsReadSearch by URL or company name
get_job_applicationReadGet full details of a specific application
parse_job_application_urlReadExtract structured data from a job posting URL
create_proposed_job_applicationWriteAdd a new proposed job to your board
add_note_to_job_applicationWriteAdd a note to an existing application

​
Connecting Claude Desktop

To use Nico with Claude Desktop, add this to your Claude Desktop configuration: 
{
  "mcpServers": {
    "nico-jobagent": {
      "url": "https://mcp.nico-jobagent.com/mcp",
      "authorization_token": "YOUR_OAUTH_TOKEN"
    }
  }
}
The MCP server requires OAuth authentication with the mcp scope. See OAuth for how to obtain a token.

​
Tools reference

​
list_job_applications

List job applications with optional filtering and pagination. Parameters:
ParameterTypeRequiredDescription
statusstringNoFilter by status group: draft, applied, interviewing, offer, finished, active
pageintegerNoPage number (default: 1)
per_pageintegerNoItems per page (default: 25)
Example response: 
{
  "job_applications": [
    {
      "id": 42,
      "title": "Senior Product Manager",
      "status": "applied",
      "company": {
        "id": 7,
        "name": "Acme Corp"
      },
      "url": "https://acme.com/careers/pm-senior",
      "location": "Berlin, Germany",
      "work_mode": "hybrid",
      "created_at": "2025-03-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 52
  }
}

​
search_job_applications

Search for job applications by URL (exact match) or company name (case-insensitive). Parameters:
ParameterTypeRequiredDescription
urlstringNo*Search by exact job posting URL
company_namestringNo*Search by company name (case-insensitive)
statusstringNoFilter results by status group
*At least one of url or company_name is required. Example response (search by URL): 
{
  "exists": true,
  "count": 1,
  "job_applications": [
    {
      "id": 42,
      "title": "Senior Product Manager",
      "status": "applied",
      "company": {
        "name": "Acme Corp"
      }
    }
  ]
}

​
get_job_application

Get the full details of a specific job application, including interviews, notes, and status history. Parameters:
ParameterTypeRequiredDescription
idintegerYesThe job application ID
Example response: 
{
  "id": 42,
  "title": "Senior Product Manager",
  "status": "applied",
  "kanban_category": "applied",
  "company": {
    "id": 7,
    "name": "Acme Corp",
    "url": "https://acme.com"
  },
  "url": "https://acme.com/careers/pm-senior",
  "location": "Berlin, Germany",
  "work_mode": "hybrid",
  "salary_min": 80000,
  "salary_max": 100000,
  "currency": "EUR",
  "period": "annual",
  "employment_type": "full-time",
  "interviews": [],
  "notes": [],
  "created_at": "2025-03-15T10:30:00Z"
}

​
parse_job_application_url

Extract structured job data from a job posting URL. Nico automatically detects the job board and parses the posting. Parameters:
ParameterTypeRequiredDescription
urlstringYesURL of the job posting to parse
Example response: 
{
  "title": "Senior Product Manager",
  "company": "Acme Corp",
  "location": "Berlin, Germany",
  "work_mode": "hybrid",
  "salary_min": 80000,
  "salary_max": 100000,
  "currency": "EUR",
  "period": "annual",
  "employment_type": "full-time"
}
Use parse_job_application_url before create_proposed_job_application to extract job details automatically — then pass the parsed data to the create tool.

​
create_proposed_job_application

Create a new job application in proposed status. The job owner must approve it before it moves forward. Parameters:
ParameterTypeRequiredDescription
titlestringYesJob title
company_namestringYesCompany name (creates company if it doesn’t exist)
urlstringNoJob posting URL
locationstringNoJob location
work_modestringNoOne of: remote, remote-optional, hybrid, on-site
salary_minnumberNoMinimum salary
salary_maxnumberNoMaximum salary
currencystringNoSalary currency (e.g., USD, EUR)
periodstringNoPay period (e.g., annual, monthly)
employment_typestringNoOne of: full-time, part-time, contract, internship, temporary
Idempotency: If a job application with the same URL already exists, the existing application is returned instead of creating a duplicate. Example response: 
{
  "id": 43,
  "title": "Senior Product Manager",
  "status": "proposed",
  "company": {
    "name": "Acme Corp"
  },
  "created": true
}

​
add_note_to_job_application

Add a note to an existing job application. Parameters:
ParameterTypeRequiredDescription
job_application_idintegerYesThe job application ID
contentstringYesThe note text
Example response: 
{
  "id": 156,
  "content": "Strong match for the candidate's background in product analytics.",
  "created_at": "2025-03-15T14:20:00Z",
  "author": "Job Search Bot"
}