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

Both paths below start with merge login, which opens a browser. If the agent is doing the setup and no person is there to complete it, take the agent quickstart instead, which needs no browser and no account.

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.