Model Context Protocol (MCP)

Merge offers an MCP server that integrates the Merge API with any LLM provider supporting the MCP protocol. This enables your AI agent to access hundreds of tools via a single MCP server.

The Merge MCP SDK can be found here.

The following items are prerequisites in order to implement Merge MCP:

• A Merge API key and linked account token
• Python 3.10 or higher
• uv

Here is an example config file which you can use to set up Merge MCP.

Note: If the uvx command does not work, try absolute path (i.e./Users/username/.local/bin/uvx). You can find the absolute path by running which uvx through your terminal.

Example Claude Desktop setup

1. Ensure you have uvx installed

2. Download Claude Desktop from the official website

3. Once downloaded, open the app and follow the instructions to set up your account

4. Navigate to Settings → Developer → Edit Config. This should open a file named claude_desktop_config.json in a text editor.

5. Copy the MCP server setup JSON above and paste it into the text editor

6. Replace your_api_key and your_account_token with your actual Merge API key and Linked Account token. You will also need to replace uvx with the absolute path to the command in the config file (i.e. /Users/username/.local/bin/uvx). You can find the absolute path by running which uvx through your terminal.

7. Save the config file

8. Restart Claude Desktop to see your tools. The tools may take a minute to appear.

Scopes determine which tools are enabled on the MCP server, and is used to control access to different parts of the Merge API.

You can specify which scopes to enable with the --scopes flag.

Scopes in the Merge MCP server follow a specific format based on the Merge API category and Common Model names. Each scope is formatted as:

<category>.<common_model_name>:<permission>

Where:

• <category> - The category of the Common Model (e.g. ats, hris, crm, etc.)
• <common_model_name> - The name of the Common Model (e.g. Candidate, Application, etc.)
• <permission> - The permission level of the Common Model (e.g. read or write)

Examples of valid scopes:

• ats.Candidate:read - Read access to Candidate objects
• hris.Employee:write - Write access to Employee objects
• crm.Contact - Read + Write access to Contact objects

You can combine multiple scopes to grant different permissions.

If no scopes are specified, all available scopes will be enabled. The available scopes depend on your Merge API account configuration and the models the Linked Account has access to.

Scopes specified with the MCP server will be validated against enabled scopes on the Linked Account. The server will only enable tools for valid authorized scopes.

The following situations can occur:

• Category Mismatch: If you specify a scope for a category that doesn't match your Linked Account (e.g., using ats.Job with an HRIS Linked Account), no tools for that scope will be returned.
• Permission Mismatch: If you request a permission that isn't enabled for your Linked Account (e.g., using hris.Employee:write when only read access is enabled), tools requiring that permission won't be returned.