Setup

Agent quickstart

Sign up, get a tool pack, and make your first tool call without a human in the loop.

This is the path for an agent that needs tools right now and has no account. One unauthenticated request creates an organization, an access key, a tool pack, and a registered user, and the response carries everything the next call needs. A human can take ownership later, or never.

Use it when the agent is the one doing the setup: a coding agent adding tool access to a project it is working on, an evaluation harness that needs a throwaway org, a trial that should not stall on someone finding a signup form. If a person is already in the loop, sign up in the dashboard and read Building an agent instead, which covers the same ground with the dashboard in front of you.

Sign up

$curl -X POST https://ah-api.merge.dev/api/v1/agent/signup/
1import requests
2
3signup = requests.post("https://ah-api.merge.dev/api/v1/agent/signup/").json()

No authentication, no request body. The endpoint is rate limited per IP, so an agent that retries in a loop will start getting rejected rather than creating orgs.

The response carries an access_key object, a claim link, and the two ids the next call needs. See the API reference for the full response schema.

1{
2  "access_key": { "...": "the organization's production key" },
3  "claim_url": "https://ah.merge.dev/claim/<token>",
4  "claim_expires_at": "2026-09-01T12:00:00Z",
5  "tool_pack_id": "9b2a5c1e-4f3d-4a6b-9c8d-1e2f3a4b5c6d",
6  "registered_user_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
7  "next_step": "Run: merge search-tools \"<intent>\". Guide: https://docs.merge.dev/merge-agent-handler/setup/agent-quickstart"
8}

Store the key before doing anything else. It is returned once and there is no account to log into and recover it from, because the organization has no users yet.

What you get

Signup returns the three things a tool call needs, rather than leaving them to a follow-up round of management calls.

FieldWhat it isWhy it’s there
access_keyAn unrestricted production key for the new organizationAuthorizes every call below
tool_pack_idA tool pack named “My first Tool Pack”, holding a curated starter set of connectorsDecides which tools exist
registered_user_idA production registered user named Agent, with origin_id of agentDecides whose credentials run the call

The starter tool pack covers twelve connectors: Asana, GitHub, Gmail, Google Calendar, Google Drive, HubSpot, Jira, Linear, Notion, Slack, Weather, and Wikipedia. It is a starting set rather than the catalog, because seeding every connector would mean thousands of rows written on an unauthenticated request. Add the connectors you actually need from Tool packs, or create a second pack and leave this one alone.

Weather and Wikipedia are in the set deliberately: neither needs a credential, so you can prove the whole path works before touching OAuth.

Make the first tool call

The Agent registered user starts with no connected credentials, so start with a connector that does not need one.

Point your MCP client at the URL assembled from the two ids:

https://ah-api.merge.dev/api/v1/tool-packs/<TOOL_PACK_ID>/registered-users/<REGISTERED_USER_ID>/mcp

Pass the key as Authorization: Bearer <ACCESS_KEY>. MCP integration has the client-by-client configuration.

From a terminal, the Merge CLI is faster to check with. Configure it with the three values from the signup response, then search and execute:

$merge configure     # paste the key, tool pack id, and registered user id
$merge search-tools "what is the weather forecast"
$merge execute-tool weather__get_forecast '{"input": {"latitude": 37.7749, "longitude": -122.4194}}'

search-tools is the call to reach for first. It returns compact schemas for the tools that match an intent, which is what keeps a full catalog out of the agent’s context.

Connect a credentialed connector

Anything reading real data needs the Agent registered user to hold a credential for it. There is no browser session to run Link in, so mint a magic link and hand the URL to whoever owns the account:

$merge execute-tool authenticate_slack '{}'

The response carries a URL. The person who opens it authenticates against their own Slack account, and the credential lands on the Agent registered user. The next slack__ tool call goes through.

For an agent serving more than one person, create a registered user per person rather than sharing the Agent one. Registered users covers why, and the isolation you get from it.

Handing the organization to a human

claim_url is how the org gets an owner. Show it whenever you want a person to take over: they open it, sign in, and become an admin of the organization that already exists, with its key, tool pack, registered user, credentials, and logs intact.

Two properties worth relying on: the key works before the claim and after it, so a handoff never interrupts a running agent, and the link stops working at claim_expires_at. If it lapses before anyone uses it, reissue a fresh one rather than signing up again, which would abandon everything the agent has already connected.

A human who claims the org lands on the same default tool pack rather than a second copy, so nothing is duplicated by the handoff.

Next

Shape what the agent can reach with Tool packs.