Fresh 2026

Model Context Protocol (MCP)

How to connect AI agents to the Merge API using Merge's MCP server. Covers setup, available tools, and configuration for Claude, Cursor, and other MCP clients.

---

Overview

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.

Installation

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

MCP setup

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

{
  "mcpServers": {
    "merge-mcp": {
      "command": "uvx",
      "args": ["merge-mcp"],
      "env": {
        "MERGE_API_KEY": "your_api_key",
        "MERGE_ACCOUNT_TOKEN": "your_account_token"
      }
    }
  }
}

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

Ensure you have uvx installed

Download Claude Desktop from the official website

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

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

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

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.

Save the config file

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

Example Python client setup

You will first need to set up a Python virtual environment and install the required dependencies.

You will also create a client.py file that will contain the code for your MCP client and be the entry point for your application.

# Create project directory
mkdir mcp-client
cd mcp-client

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On Unix or MacOS:
source .venv/bin/activate

# Install required packages
pip install mcp uv anthropic python-dotenv

# Create our main file
touch client.py

You will need to set up your API keys in the environment variables.

The ANTHROPIC_API_KEY will be used to authenticate your requests to the Anthropic API.

The MERGE_API_KEY will be needed to connect to the Merge MCP server.

# Add your ANTHROPIC_API_KEY and MERGE_API_KEY to .env
echo "ANTHROPIC_API_KEY=" >> .env
echo "MERGE_API_KEY=" >> .env

# Add .env file to .gitignore
echo ".env" >> .gitignore

The MCPClient class will handle the connection to the Merge MCP server and facilitate the calls made to the Anthropic API.

import os
import asyncio
from typing import Optional
from contextlib import AsyncExitStack

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()  # load environment variables from .env

class MCPClient:
    def __init__(self):
        # Initialize session and client objects
        self.session: Optional[ClientSession] = None
        self.exit_stack = AsyncExitStack()
        self.anthropic = Anthropic()

    # Methods will go here

The connect_to_server function will be used to connect to the MCP server.

This function takes in a linked_account_token parameter which is the token associated with the Linked Account you want to connect to.

async def connect_to_server(self, linked_account_token: str):
    """Connect to an MCP server
    Args:
        linked_account_token: The token for the associated Linked Account
    """

    server_params = StdioServerParameters(
        command="uvx",
        args=["merge-mcp"],
        env={
            "MERGE_API_KEY": os.getenv("MERGE_API_KEY"),
            "MERGE_ACCOUNT_TOKEN": linked_account_token
        }
    )

    stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
    self.stdio, self.write = stdio_transport
    self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))

    await self.session.initialize()

    # List available tools
    response = await self.session.list_tools()
    tools = response.tools
    print("\nConnected to server with tools:", [tool.name for tool in tools])

The process_query function will be used to process queries from the MCP server.

This function takes in a query parameter which is a user initiated prompt that will be sent to the Anthropic API.

The Anthropic API will return a response that will contain text or tool use. In the case of tool use, the Anthropic call will have returned a name and input corresponding to the tool that should be used and the arguments that should be passed to the tool.

This information is then surfaced to the user to prompt them for confirmation on executing the tool.

Once the user confirms, the tool name and arguments will be passed to the call_tool function of our existing session with the Merge MCP server.

The results of the tool call will be sent to another Anthropic API call to generate a response.

async def process_query(self, query: str) -> str:
    """Process a query using Claude and available tools"""
    messages = [
        {
            "role": "user",
            "content": query
        }
    ]

    response = await self.session.list_tools()
    available_tools = [{
        "name": tool.name,
        "description": tool.description,
        "input_schema": tool.inputSchema
    } for tool in response.tools]

    # Initial Claude API call
    response = self.anthropic.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1000,
        messages=messages,
        tools=available_tools
    )

    # Process response and handle tool calls
    final_text = []
    assistant_message_content = []
    for content in response.content:
        if content.type == 'text':
            final_text.append(content.text)
            assistant_message_content.append(content)

        elif content.type == 'tool_use':
            tool_name = content.name
            tool_args = content.input

            # Get confirmation for tool call execution
            confirmation = input(f"Do you want to call tool '{tool_name}' with arguments {tool_args}? (y/n): ").strip().lower()
            if confirmation.startswith('y'):
                result = await self.session.call_tool(tool_name, tool_args)
                final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")
                assistant_message_content.append(content)
                messages.append({
                    "role": "assistant",
                    "content": assistant_message_content
                })
                messages.append({
                    "role": "user",
                    "content": [
                        {
                            "type": "tool_result",
                            "tool_use_id": content.id,
                            "content": result.content
                        }
                    ]
                })

                # Get next response from Claude
                response = self.anthropic.messages.create(
                    model="claude-3-5-sonnet-20241022",
                    max_tokens=1000,
                    messages=messages,
                    tools=available_tools
                )
                final_text.append(response.content[0].text)

            else:
                final_text.append(f"[Skipped calling tool {tool_name} with args {tool_args}]")

    return "\n".join(final_text)

The chat_loop function will be used to handle chat interactions with the MCP server.

This function handles the main chat loop where the user is prompted to input a query. That query is then sent to the process_query function.

async def chat_loop(self):
    """Run an interactive chat loop"""
    print("\nMCP Client Started!")
    print("Type your queries or 'quit' to exit.")

    def get_query():
        return input("\nQuery: ").strip()

    query = get_query()

    while query.lower() != 'quit':
        try:
            response = await self.process_query(query)
            print("\n" + response)

            query = get_query()

        except Exception as e:
            print(f"\nError: {str(e)}")

The cleanup function will be used to clean up resources when the MCPClient is no longer needed.

This function will be called when the process is terminated.

async def cleanup(self):
    """Clean up resources"""
    await self.exit_stack.aclose()

The main function will be used to initiate a MCPClient instance, connect to the MCP server, and start the chat loop.

async def main():
    client = MCPClient()
    try:
        await client.connect_to_server("")
        await client.chat_loop()
    finally:
        await client.cleanup()

if __name__ == "__main__":
    import sys
    asyncio.run(main())

You can run the client by executing the client.py file.

If the set up was completed successfully, you should be prompted to input a query.

python client.py

---

Scopes

Scopes determine which tools are enabled on the MCP server and are used to control access to different parts of the Merge API. If no scopes are specified, all available scopes will be enabled.

When starting the server, you can specify which scopes to enable. This is done by passing the --scopes flag with a list of scopes.

{
  "mcpServers": {
    "merge-mcp": {
      "command": "uvx",
      "args": [
        "merge-mcp",
        "--scopes",
        "ats.Job:read",
        "ats.Candidate",
        "ats.Application:write"
      ],
      "env": {
        "MERGE_API_KEY": "your_api_key",
        "MERGE_ACCOUNT_TOKEN": "your_account_token"
      }
    }
  }
}

Scope format

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:

.:

Where:

• `` - The category of the Common Model (e.g. ats, hris, crm, etc.)
• `` - The name of the Common Model (e.g. Candidate, Application, etc.)
• `` - 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.

Important note on scopes availability

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.
• Validation: The server will automatically validate your requested scopes against what's available in your Linked Account and will only enable tools for valid, authorized scopes.

Scopes typically correspond to different models or entity types in the Merge API, and they control both read and write access to these entities.

Available tools

The Merge MCP server provides access to various Merge API endpoints as tools. The available tools depend on your Merge API category (HRIS, ATS, etc.) and the scopes you have enabled.

Tools are dynamically generated based on your Merge API schema and include operations for:

• Retrieving entity details
• Listing entities
• Creating new entities
• Updating existing entities
• And more, based on your specific Merge API configuration

Note: Download tools are not currently supported. This is a known limitation and will be addressed in a future release.

Environment variables

The following environment variables are used by the Merge MCP server:

• MERGE_API_KEY: Your Merge API key
• MERGE_ACCOUNT_TOKEN: Your Merge Linked Account token
• MERGE_TENANT (Optional): The Merge API tenant associated with your Linked Account. Valid values are US, EU, and APAC. Defaults to US.