MCPサーバーの統合

この MCP (モデルコンテキストプロトコル) サーバーは、Merge API と MCP プロトコルをサポートする任意の LLM プロバイダー (例: Claude for Desktop) との統合を提供し、自然言語を使用して Merge データを操作できるようにします。

✨ 特徴

自然言語を使用して Merge API エンティティをクエリする
Mergeデータモデルとそのフィールドに関する情報を取得します
会話型インターフェースを通じてエンティティを作成および更新する
複数の Merge API カテゴリ (HRIS、ATS など) のサポート

Related MCP server: mcp-llm

📦 インストール

前提条件

Merge APIキーとアカウントトークン
Python 3.10以上
紫外線

スタンドアロンインストーラーでuvをインストールします。

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

またはpip経由:

# With pip.
pip install uv

# With pipx.
pipx install uv

🔌 MCP セットアップ

Merge MCP を設定するために使用できる設定ファイルの例を次に示します。

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

注: 「uvx」コマンドが機能しない場合は、絶対パス（例: /Users/username/.local/bin/uvx）を試してください。

Claude Desktop の構成例

uvxがインストールされていることを確認してください
公式サイトからClaude Desktopをダウンロードしてください
ダウンロードしたら、アプリを開いて指示に従ってアカウントを設定してください。
**「設定」→「開発者」→「設定の編集」**に移動します。テキストエディターでclaude_desktop_config.jsonというファイルが開きます。
上記のMCPサーバーセットアップJSONをコピーしてテキストエディターに貼り付けます。
your_api_keyとyour_account_tokenを、実際の Merge API キーとリンク済みアカウントトークンに置き換えてください。また、 uvx設定ファイル内のコマンドへの絶対パス（例: /Users/username/.local/bin/uvx ）に置き換える必要があります。絶対パスは、ターミナルでwhich uvx実行することで確認できます。
設定ファイルを保存する
ツールを表示するには、Claude Desktopを再起動してください。ツールが表示されるまで1分ほどかかる場合があります。

Pythonクライアントの設定例

環境の設定

# 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

APIキーの設定

# Add your ANTHROPIC_API_KEY and MERGE_API_KEY to .env
echo "ANTHROPIC_API_KEY=<your Anthropic key here>" >> .env
echo "MERGE_API_KEY=<your Merge key here>" >> .env

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

client.pyファイルを作成し、次のコードを追加します。

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

MCPClientクラスにconnect_to_server関数を追加する

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])

MCPClientクラスにprocess_query関数を追加する

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)

MCPClientクラスにchat_loop関数を追加する

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

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

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

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

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

MCPClientクラスにcleanup関数を追加する

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

client.pyファイルにメインエントリポイントとしてmain関数を追加します。

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__":
    import sys
    asyncio.run(main())

クライアントの実行

python client.py

🔍 スコープ

スコープは、MCPサーバー上で有効にするツールを決定し、Merge APIの様々な部分へのアクセスを制御するために使用されます。スコープが指定されていない場合は、利用可能なすべてのスコープが有効になります。

サーバーを起動する際に、有効にするスコープを指定できます。これは、スコープのリストを指定した--scopesフラグを渡すことで実行されます。

{
    "mcpServers": {
        "merge-mcp-server": {
            "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"
            }
        }
    }
}

スコープ形式

Merge MCPサーバーのスコープは、Merge APIのカテゴリと一般的なモデル名に基づいた特定の形式に従います。各スコープの形式は以下のとおりです。

<category>.<CommonModel>:<permission>

どこ：

<category>は Merge API カテゴリです (例: hris 、 ats 、 accounting )
<CommonModel>は、マージ共通モデルの名前です (例: Employee 、 Candidate 、 Account )
<permission>はreadまたはwriteいずれかです (オプション - 指定されていない場合はすべての権限が付与されます)

有効なスコープの例:

hris.Employee:read - HRIS カテゴリから従業員データを読み取ることができます
ats.Candidate:write - ATS カテゴリの候補者データの作成または更新を許可します
accounting.Account - 会計カテゴリのアカウントデータに対するすべての操作を許可します

複数のスコープを組み合わせて、異なる権限を付与することができます。

スコープの可用性に関する重要な注意事項

利用可能なスコープは、Merge APIアカウントの設定と、リンクされたアカウントがアクセスできるモデルによって異なります。スコープは、リンクされたアカウントで有効なスコープと相互参照する必要があります。

カテゴリの不一致: リンクされたアカウントと一致しないカテゴリのスコープを指定した場合 (例: HRIS リンクされたアカウントでats.Jobを使用する)、そのスコープのツールは返されません。
権限の不一致: リンクされたアカウントで有効になっていない権限をリクエストした場合 (読み取りアクセスのみが有効になっている場合にhris.Employee:writeを使用するなど)、その権限を必要とするツールは返されません。
検証: サーバーは、要求されたスコープをリンクされたアカウントで利用可能なスコープと照らし合わせて自動的に検証し、有効で承認されたスコープに対してのみツールを有効にします。

スコープは通常、Merge API 内のさまざまなモデルまたはエンティティタイプに対応し、これらのエンティティへの読み取りアクセスと書き込みアクセスの両方を制御します。

🚀 利用可能なツール

Merge MCPサーバーは、様々なMerge APIエンドポイントへのアクセスをツールとして提供します。利用可能なツールは、Merge APIのカテゴリー（HRIS、ATSなど）と有効にしたスコープによって異なります。

ツールは Merge API スキーマに基づいて動的に生成され、次の操作が含まれます。

エンティティの詳細を取得しています
エンティティのリスト
新しいエンティティの作成
既存のエンティティの更新
さらに、特定のMerge API設定に基づいて

**注:**ダウンロードツールは現在サポートされていません。これは既知の制限であり、今後のリリースで修正される予定です。

🔑 環境変数

Merge MCP サーバーでは次の環境変数が使用されます。

MERGE_API_KEY : Merge APIキー
MERGE_ACCOUNT_TOKEN : マージリンクアカウントトークン
MERGE_TENANT (オプション): Merge APIテナント。有効な値はUS 、 EU 、 APACです。デフォルトはUSです。

Merge MCP Server