Implementation:CrewAIInc CrewAI Merge Agent Handler Tool

Knowledge Sources	CrewAI
Domains	Third-Party Integration, MCP, Tool Integration
Last Updated	2026-02-11 00:00 GMT

Overview

MergeAgentHandlerTool is a CrewAI tool that wraps the Merge Agent Handler's Model Context Protocol (MCP) to provide secure access to third-party integrations such as Linear, Jira, Slack, GitHub, and Salesforce.

Description

The tool extends BaseTool and communicates with the Agent Handler API via JSON-RPC 2.0 MCP requests. Agent Handler manages authentication, permissions, monitoring, and PII scanning for all tool interactions, enabling agents to execute actions across 100+ platforms without direct API integrations.

Key features of the implementation:

• Session management -- Automatically generates UUID-based session IDs for MCP protocol compliance.
• JSON-RPC 2.0 protocol -- The _make_mcp_request method constructs authenticated HTTP POST requests with JSON-RPC payloads, MCP-Session-Id headers, and Bearer token authentication from the AGENT_HANDLER_API_KEY environment variable.
• Dynamic schema discovery -- The from_tool_name class method fetches tool schemas from Agent Handler and dynamically creates Pydantic models from JSON schema definitions, mapping JSON types to Python types and handling optional fields.
• Bulk tool loading -- The from_tool_pack class method fetches all available tools from a Tool Pack and creates multiple tool instances, with optional filtering by tool name.

The _run method executes tools by sending tools/call requests with tool names and arguments, parsing JSON-encoded content from MCP responses.

Usage

Use this tool when agents need to interact with third-party services (e.g., create Linear issues, fetch Jira tickets, send Slack messages) through Merge's unified Agent Handler API. It is the recommended approach for secure multi-platform integration in CrewAI workflows.

Code Reference

Source Location

• Repository: CrewAI
• File: lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py
• Lines: 1-363

Signature

class MergeAgentHandlerTool(BaseTool):
    tool_pack_id: str = Field(..., description="UUID of the Agent Handler Tool Pack to use")
    registered_user_id: str = Field(..., description="UUID or origin_id of the registered user")
    tool_name: str = Field(..., description="Name of the specific tool to execute")
    base_url: str = Field(default="https://ah-api.merge.dev", description="Base URL for Agent Handler API")
    session_id: str | None = Field(default=None, description="MCP session ID (generated if not provided)")
    env_vars: list[EnvVar]  # Requires AGENT_HANDLER_API_KEY

Import

from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerTool

I/O Contract

Inputs

Name	Type	Required	Description
tool_pack_id	str	Yes	UUID of the Agent Handler Tool Pack
registered_user_id	str	Yes	UUID or origin_id of the registered user
tool_name	str	Yes	Name of the specific tool to execute (e.g., "linear__create_issue")
base_url	str	No	Base URL for Agent Handler API (default: "https://ah-api.merge.dev")
**kwargs	Any	Varies	Tool-specific arguments passed to the MCP tools/call request

Outputs

Name	Type	Description
return	Any	Parsed JSON response from the tool execution, or raw text content if JSON parsing fails

Usage Examples

Basic Usage

import os
os.environ["AGENT_HANDLER_API_KEY"] = "your-api-key"

from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerTool

# Create a single tool from a tool name
tool = MergeAgentHandlerTool.from_tool_name(
    tool_name="linear__create_issue",
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa"
)
result = tool._run(title="Bug fix", description="Fix the login page")

# Load all tools from a Tool Pack
tools = MergeAgentHandlerTool.from_tool_pack(
    tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3",
    registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
    tool_names=["linear__create_issue", "linear__get_issues"]
)