# Marvin Recruiter MCP server

[Français](README.fr.md)

The official remote [Model Context Protocol](https://modelcontextprotocol.io) server of
[Marvin Recruiter](https://marvins.ai), the recruitment software for recruitment agencies,
IT consultancies and staffing firms, published by MARVIN SAS (Paris, France).

It gives Claude, ChatGPT, Cursor and other MCP clients access to your firm's recruitment
database (candidates, contacts, companies, jobs, hiring processes, missions and timesheets,
notes, lists, sequences and history), with the permissions of your own Marvin account.

```
https://mcp.marvins.ai/mcp
```

This repository holds the documentation and the [`server.json`](server.json) published to the
[official MCP Registry](https://registry.modelcontextprotocol.io). It contains no server code:
the server is a hosted service, operated by Marvin.

- Product page: https://marvins.ai/en/mcp
- Privacy policy: https://marvins.ai/en/privacy
- Support: support@marvinrecruiter.com

## Requirements

- A Marvin Recruiter account, with a seat in your firm's workspace. There is no anonymous
  access and no shared key: each user connects with their own account.
- The MCP server is included in every Marvin plan, with no per-request credit. Your AI
  assistant subscription stays your own.

## At a glance

| | |
| --- | --- |
| Endpoint | `https://mcp.marvins.ai/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 with PKCE and dynamic client registration (RFC 7591) |
| OAuth metadata | `https://mcp.marvins.ai/.well-known/oauth-protected-resource`, `https://mcp.marvins.ai/.well-known/oauth-authorization-server` |
| Capabilities | tools, resources, prompts |
| Tools | 53 |
| Prompts | 8 |

## Connect

The same address works for every firm: your sign-in decides the account, the workspace and
the permissions. On first use, your client opens a browser window: sign in to Marvin (the
sign-in page uses your Google account; if a Marvin session is already open in the same
browser, it is reused) and approve the access.

### Claude (web and desktop)

Settings → Connectors → Add custom connector, then paste `https://mcp.marvins.ai/mcp`.

### Claude Code

```bash
claude mcp add --transport http marvin https://mcp.marvins.ai/mcp
```

Then run `/mcp` in Claude Code and choose the server to sign in.

### ChatGPT

Settings → Connectors (Apps), add a custom connector with the URL `https://mcp.marvins.ai/mcp`
and the OAuth authentication. Availability of custom connectors depends on your ChatGPT plan
and workspace settings.

### Cursor and other clients that use an `mcp.json` file

Use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which handles the
OAuth sign-in through your browser (requires Node.js 18 or later):

```json
{
  "mcpServers": {
    "marvin": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.marvins.ai/mcp"]
    }
  }
}
```

Keep the `@latest` suffix: older versions of `mcp-remote` can hang on tool calls.

### Any other MCP client

Point the client at `https://mcp.marvins.ai/mcp` with the Streamable HTTP transport. The
server answers unauthenticated requests with `401` and a `WWW-Authenticate` header that
points to its OAuth metadata, so clients that implement MCP authorization discover the
sign-in on their own.

## Security

- One sign-in per user (OAuth 2.1). No shared token.
- Every request is limited to the user's firm and follows Marvin roles: a record from
  another firm returns nothing, and the assistant cannot do anything the user's account
  could not do. Actions are recorded under the user's name.
- Sensitive actions (sending a message, enrolling people in a sequence, publishing a job,
  deleting or merging records, paid enrichment) start as a preview. They only run after
  the user confirms, in the client's confirmation form when it has one, or in Marvin.
- Data is hosted in France.

## Tools

Tool names are stable identifiers. Some tools depend on the features enabled in your
workspace (connected LinkedIn or email account, job board publishing, contact enrichment
credits) or on your role (admin-only tools are marked). A workspace admin can choose a
lighter tool set to make the assistant faster.

### Search and read

| Tool | What it does |
| --- | --- |
| `search` | Search candidates, contacts, companies, jobs, processes, missions, notes and other records, with filters. |
| `count` | Count records matching filters. |
| `read_resource` | Read a record in full (job description, resume text, company profile...). |
| `boolean_search` | Keyword search with boolean operators across profiles. |
| `stats` | Grouped statistics on records (by stage, owner, status, period...). |
| `stale_entities` | Find records with no recent activity, to follow up. |
| `run_saved_search` | Run one of the user's saved searches. |
| `recent_searches` | List the user's recent searches. |
| `custom_fields_list` | List the custom fields defined by the workspace. |
| `list_team_members` | List the members of the firm. |
| `get_authenticated_user` | Show the connected account and workspace. |
| `help` | Look up Marvin's documentation. |

### Create and update

| Tool | What it does |
| --- | --- |
| `create` | Create a record (candidate, contact, company, job, process, note, reminder, list...). |
| `update` | Update a record. |
| `duplicate_job` | Duplicate an existing job as a new one. |
| `merge_records` | Merge duplicate people or companies (preview first, can be undone for 30 days). |
| `manage_taxonomy` | Curate the workspace's jobs and skills reference (admins). |
| `export` | Export a list of companies as CSV (admins, when enabled for the workspace). |

### Delete

| Tool | What it does |
| --- | --- |
| `delete_record` | Delete a person, company or job (preview first, explicit confirmation). |
| `delete_note` | Delete a note. |
| `delete_list` | Delete a list. |
| `delete_reminder` | Delete a reminder. |

### Pipeline and applications

| Tool | What it does |
| --- | --- |
| `advance_process_stage` | Move a candidate to another stage of a hiring process. |
| `add_feedback` | Add interview feedback to a process. |
| `schedule_next_interview` | Record the next interview of a process in Marvin, with a reminder (no calendar invitation is sent). |
| `close_job_pipeline` | Close all remaining candidates of a job in one go (preview first). |
| `applications` | List incoming applications for a job, accept or decline them (preview first). |

### Matching

| Tool | What it does |
| --- | --- |
| `match_candidates_to_job` | Find candidates in the database who fit a job. |
| `match_jobs_to_person` | Find jobs that fit a candidate. |
| `find_similar_persons` | Find profiles similar to a given person. |
| `find_similar_jobs` | Find jobs similar to a given job. |
| `score_candidates_for_job` | Rank candidates for a job, with the reasons for each score. |
| `compare_candidates` | Compare several candidates against a job. |

### Writing and analysis

These tools gather the data from Marvin and, where the client supports MCP sampling, have
your own assistant write the text.

| Tool | What it does |
| --- | --- |
| `draft_outreach_for_person` | Draft a personalised outreach message. |
| `find_and_outreach` | Find candidates for a job and draft a message for each. |
| `generate_brief_from_process` | Write a candidate brief for the client from a hiring process. |
| `summarize_person_activity` | Summarise the recent activity on a record. |
| `suggest_next_action` | Suggest the next step for a process. |
| `generate_interview_questions` | Prepare interview questions for a candidate and a job. |
| `detect_duplicate_persons` | Detect likely duplicate people. |
| `auto_tag_person` | Suggest tags for a person. |

### Outreach

| Tool | What it does |
| --- | --- |
| `send_message` | Send a LinkedIn, email or WhatsApp message, or a LinkedIn invitation, from the user's connected account (preview first). |
| `enroll_in_sequence` | Enrol people in an outreach sequence (preview first). |

### LinkedIn and enrichment

| Tool | What it does |
| --- | --- |
| `linkedin_search` | Search LinkedIn profiles through the user's connected account. |
| `linkedin_lookup_profile` | Look up a LinkedIn profile. |
| `import_linkedin_profile` | Import a LinkedIn profile into the database. |
| `enrich_person_from_linkedin` | Update a record from its LinkedIn profile. |
| `enrich_person_contact` | Find a professional email or phone number, using the firm's enrichment credits (cost shown and confirmed first). |

### Job publishing

| Tool | What it does |
| --- | --- |
| `diffuse_job_to_boards` | Publish a job on the job boards configured by the firm (preview first). |
| `unpublish_job_from_board` | Remove a job from a job board. |
| `manage_career_page` | Publish a job on the firm's career page, or take it down. |

### Marvin actions

| Tool | What it does |
| --- | --- |
| `find_actions` | Find an action available in Marvin's built-in assistant. |
| `execute_action` | Run that action, with the same confirmation rules as in Marvin. |

## Prompts

| Prompt | What it produces |
| --- | --- |
| `brief-candidate` | A structured candidate brief, ready to send to the client. |
| `interview-summary` | A summary of the latest interview of a process. |
| `sourcing-plan` | A sourcing plan for a job: target personas, keywords, expected volume. |
| `relance-candidat` | A short, personalised follow-up message to a candidate. |
| `recap-pipeline` | The state of a job's pipeline, stage by stage, with highlights and risks. |
| `bilan-mission` | A review of a consulting or interim management mission. |
| `prepa-rendez-vous` | Preparation notes for a client meeting. |
| `cartographie-marche` | A market map for a job or a sector: target companies, profiles already in the database, priorities. |

## License

The documentation in this repository is released under the [MIT License](LICENSE). The
Marvin name and logo are not covered by this license. The Marvin service is subject to its
own terms.