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

# Quickstart

> End-to-end Agent Handler quickstart with two paths: MCP or Merge CLI. Connect from Cursor, Claude Code, or any MCP client; make a real tool call against GitHub.

Sign up, point your IDE at Agent Handler, and call a real GitHub tool. Both paths below sign you in through your IdP - no API key required.

You'll need an [Agent Handler account](https://ah.merge.dev/signup) and an MCP-capable client (Cursor, Claude Code, Windsurf, VS Code). Signing up needs no card: the free plan comes with monthly credits, one per tool call, and [Billing and usage](/merge-agent-handler/administer/billing) covers what happens when they run out.

If the agent is doing the signup and there's no person to click through it, take the [agent quickstart](/merge-agent-handler/setup/agent-quickstart) instead: one unauthenticated request creates the org, the key, a tool pack, and a registered user.

#### Connect Agent Handler

Pick one path.

### Option A: MCP

First, sign in to the Merge CLI (one-time). The MCP server uses your Merge credentials:

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

Then add Agent Handler to your client. The first connection opens your browser for OAuth.

#### 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 via **MCP: Open User Configuration**:

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

### Option B: Merge CLI

For Claude Code, Cursor, or any agent that reads `AGENTS.md`. The setup command is idempotent, safe to re-run from any project root.

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

#### Claude Code

```bash
merge setup claude-code
```

#### Cursor

```bash
merge setup cursor
```

#### Codex / AGENTS.md

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

#### Call a tool

In your agent, ask:

> What repos do I own with open pull requests assigned to me?

The agent picks GitHub's `list_repositories` and `list_pull_requests`. The first call returns a Magic Link - click it, complete OAuth, and the agent retries automatically.

## Next

Pick the setup that fits your product. [Use cases](/merge-agent-handler/use-cases) compares the three side by side.

The paths above sign you in through your IdP. When your own backend starts calling Agent Handler, it authenticates with an [Access Key](/merge-agent-handler/administer/access-keys) instead. Your production key is organization-wide, so once you serve real users, hand agents a [user-scoped key](/merge-agent-handler/secure/scoping-access-per-user) minted from it rather than the key itself.