Merge MCP

🚀 Guide to Merging MCP Client

This guide aims to assist users in interacting with the Merge API through the Merge Common Model (MCP) server. We provide a Python client that you can use to connect to the MCP server and perform various operations.

📦 Installation

💻 Install Dependencies

To run the MCP client, you need to install the following Python packages:

pip install python-merapi uvicorn[aiohttp] websockets

🔌 Start the MCP Server

Before starting the MCP server, make sure all necessary dependencies are installed. Here is an example command to start the server:

uvicorn --reload server.main:app

🛠️ Configure the MCP Server

The MCP server is configured through the configuration file server_config.json. This file should contain the following content:

{
    "mcpServers": {
        "merge-mcp-server": {
            "command": "uvicorn",
            "args": ["main:app"],
            "env": {
                "MERGE_API_KEY": "your_api_key",
                "MERGE_ACCOUNT_TOKEN": "your_account_token"
            }
        }
    }
}

🛡️ Security Considerations

When configuring the MCP server, ensure that you do not hard - code sensitive information (such as API keys and account tokens) into the configuration file. It is recommended to use environment variables to manage these values.

💻 Usage Examples

Basic Usage

Here is the complete content of the client.py file:

import os
import sys
import asyncio
from typing import Dict, List, Optional

import websockets
import merapi


class MCPClient:
    def __init__(self):
        self.exit_stack = None
        self.client = None

    async def connect_to_server(self, account_token: str):
        try:
            self.client = await merapi.Client.create(
                api_key=os.getenv("MERGE_API_KEY"),
                account_token=account_token,
                scopes=[],
                tenant=os.getenv("MERGE_TENANT", "US")
            )
            await self.client.connect()
        except Exception as e:
            print(f"Error connecting to the server: {str(e)}")
            raise

    async def process_query(self, query: str) -> str:
        try:
            response = await self.client.process(query)
            return response
        except Exception as e:
            return f"Error processing the query: {str(e)}"

    async def chat_loop(self):
        print("\nMCP client has been started!")
        print("Enter your question or 'exit' to quit.")

        while True:
            try:
                query = input("\nQuery: ").strip()

                if query.lower() == 'exit':
                    break

                response = await self.process_query(query)
                print("\n" + response)

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

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

async def main():
    client = MCPClient()
    try:
        await client.connect_to_server("<your Linked Account token here>")
        await client.chat_loop()
    finally:
        await client.cleanup()

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

Environment Variables

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

📦 Scopes

Scopes determine the tools 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 by passing the --scopes flag and a list of scopes:

merge-mcp --scopes ats.Job:read ats.Candidate ats.Application:write

Scope Format

The scopes of the Merge MCP server follow a specific format based on the Merge API categories and common model names. The format of each scope is as follows:

<Category>.<CommonModel>:<Permission>

Where:

• <Category> is the category of the Merge API (e.g., hris, ats, accounting)
• <CommonModel> is the name of the Merge common model (e.g., Employee, Candidate, Account)
• <Permission> is read or write (Optional - if not specified, defaults to read)

Example

merge-mcp --scopes hris.Employee:read hris.Manager:write ats.Job:*

🚀 Running the MCP Client

1. Ensure that all necessary dependencies are installed.
2. Update <your Linked Account token here> in the client.py file with your own Linked Account token.
3. Run the following command to start the client:

python client.py

📝 Notes

• The MCP client is asynchronous, so make sure to handle asynchronous operations correctly in your environment.
• When using it in a production environment, configure error handling and logging as needed.

🤑 Frequently Asked Questions

1. How to specify custom scopes?

When starting the server, you can specify custom scopes by passing the --scopes flag:

merge-mcp --scopes ...

⚠️ Important Note

When configuring the MCP server, ensure that you do not hard - code sensitive information (such as API keys and account tokens) into the configuration file. It is recommended to use environment variables to manage these values.

💡 Usage Tip

The MCP client is asynchronous, so make sure to handle asynchronous operations correctly in your environment. When using it in a production environment, configure error handling and logging as needed.