Setup

Local development

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

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

  • 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.
  • Merge CLI - 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.).

Option 1 - MCP server

Point your IDE’s 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

Add 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

Authenticate your tools

The first time your agent calls a Connector you added, a Magic Link will appear so you can authenticate that account. Once authenticated, Agent Handler stores the credential and reuses it for future calls.

6

Use your tools

Ask your agent to perform a task that uses one of the tools you added.

Option 2 - Merge CLI

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.

Next

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