Setup

Local development

Connect Agent Handler to a locally running agent via Merge CLI or MCP.

There are two ways to give your local agent access to Agent Handler tools:

  • Merge CLI (recommended) - two commands plus a one-line setup that wires the CLI into your agent’s config. Works with Claude Code, Cursor, and any agent that reads AGENTS.md (Codex, Aider, etc.).
  • MCP server - point your IDE’s MCP config directly at Agent Handler’s hosted MCP URL. Use this for IDEs without a merge setup target (Windsurf, VS Code) or if you’d rather configure MCP yourself.

Option 1 - Merge CLI (recommended)

1

Install the CLI

Install with pipx for an isolated environment. Requires Python 3.10+.

$pipx install merge-api
2

Sign in

Opens your browser for OAuth and stores the token locally.

$merge login
3

Connect the CLI to your agent

merge setup writes a short usage guide into your agent’s instruction file so it knows when to call merge search-tools and merge execute-tool. Pick your agent:

$merge setup claude-code

Writes a ## Merge CLI section to CLAUDE.md and adds Bash(merge *) to .claude/settings.json so Claude Code can run the CLI without prompting.

Run from the root of the project where you want the agent to use Merge tools. Re-run safely - the command is idempotent.

4

Make a tool call

Open your agent and try a prompt like:

List all the repos I have access to in GitHub, and my open PRs in each.

The first time your agent uses a Connector, you’ll get a Magic Link to authenticate that account. After that, your agent can call tools on your behalf.

Option 2 - MCP server

If your IDE doesn’t have a merge setup target, point its MCP config at Agent Handler’s hosted MCP URL.

1

Sign in to the CLI (one-time)

The MCP server uses your Merge credentials. If you haven’t already:

$pipx install merge-api
$merge login
2

Add Agent Handler to your IDE

Pick your client:

$claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp
3

Verify the connection

Restart your IDE and confirm agent-handler appears in its MCP server list. In Claude Code, run:

/mcp

You should see agent-handler listed under Local MCPs with a connected status.

4

Authenticate your tools

Select the agent-handler MCP from the list. This opens a browser window where you can pick the tools you want your agent to access.

Tool selection screen
5

Use your tools

Ask your agent to perform a task. The first time it uses a Connector, a Magic Link will appear to authenticate that account. Once authenticated, your agent can call that tool on your behalf.

Next

Configure what tools your agent should be able to call with Tool Packs.