MCPサーバーの統合
この MCP (モデル コンテキスト プロトコル) サーバーは、Merge API と MCP プロトコルをサポートする任意の LLM プロバイダー (例: Claude for Desktop) との統合を提供し、自然言語を使用して Merge データを操作できるようにします。
✨ 特徴
- 自然言語を使用して Merge API エンティティをクエリする
- Mergeデータモデルとそのフィールドに関する情報を取得します
- 会話型インターフェースを通じてエンティティを作成および更新する
- 複数の Merge API カテゴリ (HRIS、ATS など) のサポート
📦 インストール
前提条件
- 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())
- クライアントの実行
🔍 スコープ
スコープは、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です。