> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# 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:

* **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](/merge-agent-handler/setup/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.

#### Sign in to the CLI (one-time)

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

```bash
pipx install merge-api
merge login
```

#### Add Agent Handler to your IDE

Pick your client:

#### Claude Code

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

#### Codex

```bash
codex mcp add agent-handler --url https://ah-api.merge.dev/mcp
```

#### Cursor

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

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

#### Windsurf

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

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

#### VS Code

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

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

#### Other MCP clients

Most MCP clients accept the standard `mcpServers` JSON shape:

```json
{
  "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.

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

#### 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](/_fern-img/19604b4057953f77fe436d0d38c69f17e92a4bf9a59bc718247962961e81aa14.webp)

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

#### Use your tools

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

## Option 2 - Merge CLI

#### Install the CLI

Install with [pipx](https://pipx.pypa.io/) for an isolated environment. Requires Python 3.10+.

```bash
pipx install merge-api
```

#### Sign in

Opens your browser for OAuth and stores the token locally.

```bash
merge login
```

#### 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:

#### Claude Code

```bash
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.

#### Cursor

```bash
merge setup cursor
```

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

#### Codex / AGENTS.md

```bash
merge setup agents-md
```

Writes a `## Merge CLI` section to `AGENTS.md`. Use this for any agent that follows the [AGENTS.md](https://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.

#### 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](/merge-agent-handler/build/tools/tool-packs).