Fresh 2026

Local development

How to install the Merge CLI, authenticate, and connect Agent Handler to your local coding agent.

---

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)

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

pipx install merge-api

Opens your browser for OAuth and stores the token locally.

merge login

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.

merge setup cursor

Writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services.

merge setup agents-md

Writes a ## Merge CLI section to AGENTS.md. Use this for any agent that follows the AGENTS.md convention - Codex, Aider, and others.

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

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.

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

pipx install merge-api
merge login

Pick your client:

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

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "agent-handler": {
      "url": "https://ah-api.merge.dev/mcp"
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agent-handler": {
      "serverUrl": "https://ah-api.merge.dev/mcp"
    }
  }
}

Add to .vscode/mcp.json (workspace) or your user profile via the MCP: Open User Configuration command:

{
  "servers": {
    "agent-handler": {
      "type": "http",
      "url": "https://ah-api.merge.dev/mcp"
    }
  }
}

Most MCP clients accept the standard mcpServers JSON shape:

{
  "mcpServers": {
    "agent-handler": {
      "url": "https://ah-api.merge.dev/mcp"
    }
  }
}

Check your client's docs for the exact field names - some use serverUrl instead of url, and some require a type: "http" field.

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.

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.

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.