MCP Server

Nico exposes a Model Context Protocol (MCP) server that lets AI assistants like Claude interact with Nico directly.

What can the MCP server do?

The MCP server provides 12 tools in three groups: job posting search (job_posting_*, discover openings in Nico’s index), job application management (job_application_*, your own tracked applications), and interviews (schedule and manage interviews on your applications).

Tool	Group	Type	Description
`job_posting_search`	Posting search	Read	Search Nico’s job postings index
`job_posting_get`	Posting search	Read	Get one posting’s full detail, incl. the application URL
`job_application_search`	Application mgmt	Read	Search your saved applications by URL or company name
`job_application_list`	Application mgmt	Read	List your applications with filtering and pagination
`job_application_get`	Application mgmt	Read	Get full details of one application, incl. notes and interviews
`job_application_parse_url`	Application mgmt	Read	Extract structured data from a job posting URL
`job_application_create`	Application mgmt	Write	Add a new proposed application to your board
`job_application_add_note`	Application mgmt	Write	Add a note to an existing application
`interview_list`	Interviews	Read	List all your interviews, with time filters (today, next 7 days, upcoming, past)
`job_application_interviews`	Interviews	Read	List the interviews for one application
`job_application_add_interview`	Interviews	Write	Schedule an interview for an application
`interview_update`	Interviews	Write	Reschedule or edit an existing interview

Job posting search (job_posting_search, job_posting_get) searches Nico’s shared posting index — not your own applications. To check “have I already saved this?”, use job_application_search. Posting search requires job search to be enabled for your account.

Connecting your AI assistant

The server URL for all assistants is:

https://mcp.nico-jobagent.com/mcp

Authentication is handled via OAuth — you never paste a token, API key, or client ID. Nico supports dynamic client registration, so your assistant registers itself automatically. When you add the connector, you’re redirected to Nico’s consent screen; click Authorize and you’re connected.

Claude (Desktop and claude.ai)

Go to Settings → Connectors and choose Add custom connector.
Enter a name (e.g. “Nico”) and the server URL above. Leave the advanced OAuth fields blank.
Click Connect and approve access on Nico’s consent screen.

ChatGPT

Custom MCP connectors in ChatGPT require developer mode, which is available on paid plans (Plus, Pro, Business/Enterprise).

Enable developer mode: go to Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
Go back to Apps & Connectors and choose Create to add a custom connector.
Enter a name (e.g. “Nico”), the server URL above, and select OAuth as the authentication method. Leave the client ID and secret blank — ChatGPT registers itself automatically.
Complete the connection and approve access on Nico’s consent screen.

For a visual walkthrough of enabling remote MCP servers in ChatGPT, see Enable Remote MCP Servers in ChatGPT (Step-by-Step).

The MCP server requires OAuth authentication with the mcp scope — the connector requests it automatically. See OAuth for details on the flow, scopes, and revoking access.

Job posting search

job_posting_search

Search Nico’s job postings index — the same data behind the in-app job search at /jobs. Returns the most recent matching postings, newest-first, in compact form (no application URL or description — fetch those with job_posting_get). Parameters:

Parameter	Type	Required	Description
`country_code`	string	Yes	ISO 3166-1 alpha-2 country code, e.g. `US` or `NL`. Always required.
`title`	string[]	No	Title phrases ORed together. Each phrase is a case-insensitive substring match. Example: `["backend engineer", "staff engineer"]`
`region`	string	No	State/province name (case-insensitive). Required when `city` is set and `country_code` is `US` or `CA`.
`city`	string	No	City name for radius search. Looked up exactly against Nico’s geocoded locations index — no external geocoding is performed. Returns an error if the city is unknown or ambiguous.
`radius_km`	integer	No	Search radius in km around the resolved `city` (default `25`, max `250`). Only used when `city` is set.
`work_mode`	string[]	No	One or more of `remote`, `onsite`. Hybrid postings surface under either filter.
`employers`	string[]	No	Filter to postings at these employers. Pass employer names — lookup is case-insensitive. Each name must resolve to exactly one employer; unknown or ambiguous names return an error. Example: `["Anthropic", "Stripe"]`
`limit`	integer	No	Results per page (default `20`, max `100`).
`page`	integer	No	Page number (default `1`). Use the response’s `pagination` block to walk further pages.

Don’t combine a geographic filter (region or city) with work_mode: ["remote"]. Remote postings aren’t pinned to a location, so that combination almost always returns nothing. Search remote roles by country, and use region/city for on-site or hybrid roles.

City radius search: Pass city together with country_code (plus region for US/CA) to filter postings within radius_km of that city. Cities are resolved by exact, case-insensitive match against Nico’s existing geocoded-locations index — there is no live geocoding fallback, so unknown or ambiguous names return an error rather than a best-guess match.

{
  "city": "Amsterdam",
  "country_code": "NL",
  "radius_km": 50
}

{
  "city": "Springfield",
  "region": "Illinois",
  "country_code": "US",
  "radius_km": 50
}

Example response:

{
  "job_postings": [
    {
      "id": "019e1e37-ff01-7870-a56a-7b316b2d2373",
      "title": "Senior Backend Engineer",
      "company_name": "Acme Co",
      "company_id": "019e1e37-aa01-7870-a56a-7b316b2d2374",
      "location": "San Francisco, CA / Hybrid",
      "work_mode": "hybrid",
      "employment_type": "full-time",
      "salary_min": 150000,
      "salary_max": 200000,
      "salary_currency": "USD",
      "salary_period": "annual",
      "posted_at": "2026-05-12T08:00:00Z",
      "effective_posted_at": "2026-05-12T08:00:00Z"
    }
  ],
  "count": 20,
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 99,
    "per_page": 20
  }
}

Search results omit url and description to stay compact. Take a result’s id and call job_posting_get to retrieve the application URL and the full description. Errors: The tool returns a single-key error object when the request can’t proceed:

{ "error": "country_code is required" }

Other error messages you may see:

country_code is required — country_code is mandatory on every call.
region (state/province) is required for city search in US (or CA) — region must be set when city is given and the country is US or CA.
Location not found: <city> — the city wasn’t found in Nico’s geocoded locations index.
Ambiguous location: multiple matches for <city> — please refine — more than one row matched; narrow with region.
Unknown employer: <name> — a name in employers didn’t match any employer.
Ambiguous employer: multiple matches for <name> — please refine — a name in employers matched more than one employer; refine the spelling.
Job search is not enabled for this account — the calling account doesn’t have job search enabled.

job_posting_get

Get one job posting by the id returned from job_posting_search. Returns the same fields as a search result, plus the external application url and the full description (the two fields the search list omits). Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	The posting `id` from `job_posting_search` results.

Example response:

{
  "id": "019e1e37-ff01-7870-a56a-7b316b2d2373",
  "title": "Senior Backend Engineer",
  "company_name": "Acme Co",
  "company_id": "019e1e37-aa01-7870-a56a-7b316b2d2374",
  "location": "San Francisco, CA / Hybrid",
  "work_mode": "hybrid",
  "employment_type": "full-time",
  "salary_min": 150000,
  "salary_max": 200000,
  "salary_currency": "USD",
  "salary_period": "annual",
  "posted_at": "2026-05-12T08:00:00Z",
  "effective_posted_at": "2026-05-12T08:00:00Z",
  "url": "https://acme.test/jobs/be-eng",
  "description": "About the role…"
}

Returns { "error": "Job posting not found" } for an unknown id. Same feature-flag gate as job_posting_search.

After finding a relevant posting, call job_posting_get for its url, then pass that URL to job_application_parse_url to extract richer structured fields, and finally job_application_create to add it to your board.

Job application management

job_application_search

Search your job applications by URL (exact match) or company name (case-insensitive). Parameters:

Parameter	Type	Required	Description
`url`	string	No*	Search by exact job posting URL
`company_name`	string	No*	Search by company name (case-insensitive)
`status`	string	No	Filter results by status group: `draft`, `applied`, `interviewing`, `offer`, `finished`, `active`

*At least one of url or company_name is required. Example response (search by URL):

{
  "exists": true,
  "count": 1,
  "job_applications": [
    {
      "id": "019e1e40-1234-7000-9abc-1111aaaa2222",
      "title": "Senior Product Manager",
      "status": "applied",
      "company": { "name": "Acme Corp" }
    }
  ]
}

job_application_list

List your job applications with optional filtering and pagination. Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter by status group: `draft`, `applied`, `interviewing`, `offer`, `finished`, `active`
`page`	integer	No	Page number (default `1`)
`per_page`	integer	No	Items per page (default `25`, max `100`)

Example response:

{
  "job_applications": [
    {
      "id": "019e1e40-1234-7000-9abc-1111aaaa2222",
      "title": "Senior Product Manager",
      "url": "https://acme.com/careers/pm-senior",
      "status": "applied",
      "work_mode": "hybrid",
      "location": "Berlin, Germany",
      "company_name": "Acme Corp",
      "created_at": "2026-03-15T10:30:00Z",
      "updated_at": "2026-03-16T09:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 52,
    "total_pages": 3
  }
}

job_application_get

Get the full details of one job application, including its notes and interviews. Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	The job application `id`

Example response:

{
  "id": "019e1e40-1234-7000-9abc-1111aaaa2222",
  "title": "Senior Product Manager",
  "url": "https://acme.com/careers/pm-senior",
  "status": "applied",
  "work_mode": "hybrid",
  "location": "Berlin, Germany",
  "salary_min": 80000,
  "salary_max": 100000,
  "salary_currency": "EUR",
  "salary_period": "annual",
  "company": { "id": "019e1e37-aa01-7870-a56a-7b316b2d2374", "name": "Acme Corp", "url": "https://acme.com" },
  "notes": [],
  "interviews": [],
  "created_at": "2026-03-15T10:30:00Z"
}

Returns { "error": "Job application not found" } for an unknown id.

job_application_parse_url

Extract structured job data from a job posting URL. Nico automatically detects the job board and parses the posting. Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	URL 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 job_application_parse_url before job_application_create to extract job details automatically — then pass the parsed data to the create tool.

job_application_create

Create a new job application in proposed status. The account owner must approve it before it moves forward. Parameters:

Parameter	Type	Required	Description
`title`	string	Yes	Job title
`company_name`	string	Yes	Company name (creates the company if it doesn’t exist)
`url`	string	No	Job posting URL
`location`	string	No	Job location
`work_mode`	string	No	One of: `remote`, `remote-optional`, `hybrid`, `on-site`

Idempotency: If an application with the same url already exists, the tool returns { "error": "A job application with this URL already exists", "existing_job_application_id": "<id>" } instead of creating a duplicate. Example response:

{
  "job_application": {
    "id": "019e1e41-5678-7000-9abc-3333bbbb4444",
    "title": "Senior Product Manager",
    "url": "https://acme.com/careers/pm-senior",
    "status": "proposed",
    "work_mode": "hybrid",
    "location": "Berlin, Germany",
    "company_name": "Acme Corp",
    "created_at": "2026-03-15T14:20:00Z"
  }
}

job_application_add_note

Add a note to an existing job application. Notes are visible to all team members. Parameters:

Parameter	Type	Required	Description
`job_application_id`	string	Yes	The job application `id`
`body`	string	Yes	The note text (max 10,000 characters)

Example response:

{
  "note": {
    "id": "019e1e42-9abc-7000-9abc-5555cccc6666",
    "body": "Recruiter replied — call scheduled for Friday.",
    "author": "Alex",
    "job_application_id": "019e1e41-5678-7000-9abc-3333bbbb4444",
    "created_at": "2026-03-15T14:20:00Z"
  }
}

Overview

AI Agents

Authentication

External Tools

MCP Server

MCP Server

What can the MCP server do?

Connecting your AI assistant

Claude (Desktop and claude.ai)

ChatGPT

Job posting search

job_posting_search

job_posting_get

Job application management

job_application_search

job_application_list

job_application_get

job_application_parse_url

job_application_create

job_application_add_note

​MCP Server

​What can the MCP server do?

​Connecting your AI assistant

​Claude (Desktop and claude.ai)

​ChatGPT

​Job posting search

​job_posting_search

​job_posting_get

​Job application management

​job_application_search

​job_application_list

​job_application_get

​job_application_parse_url

​job_application_create

​job_application_add_note

MCP Server

What can the MCP server do?

Connecting your AI assistant

Claude (Desktop and claude.ai)

ChatGPT

Job posting search

job_posting_search

job_posting_get

Job application management

job_application_search

job_application_list

job_application_get

job_application_parse_url

job_application_create

job_application_add_note