Merge API Documentation

At a glance

Agent Handler runs three ways - same product surface, different end user and auth model. Most teams pick one; some run two in parallel.

	Building an agent	Context layer for employees	Local development
Who’s the end user?	Your customer’s user	Your employee	You, the developer
Agent Handler auth	Your API key	OAuth via your IdP (SSO)	OAuth via `merge login`
Third-party auth	Through Link, embedded in your product	Through Magic Link, returned to the employee’s AI assistant	Through Magic Link, returned to your agent
Where does the MCP URL live?	Your backend (kept private)	The user’s MCP client config	Your MCP client config
Tool set scoped by	The Tool Pack in your MCP URL	The Tool Pack mapped to the user’s IdP Group	The Tool Pack on `merge login`
Setup guide	Building an agent	Context layer for employees	Local development

Building an agent

Your customers use your product, and your product has an agent. Each customer connects their own Salesforce, their own Slack, their own GitHub. You never touch their credentials directly - Agent Handler holds them, scoped to one Registered User per customer user.

Pick this when:

You’re a B2B SaaS shipping an agent feature to your customers.
You need credential isolation per customer (one customer’s Salesforce token can’t be used to read another customer’s data).
You want to render Link inside your own UI so the auth flow feels native.

Read Building an agent.

Context layer for employees

Your own team uses an agent that connects to your company’s tools. Auth runs through your IdP - Okta, Azure AD, Google Workspace, whichever. SCIM provisions users into Agent Handler. IdP Groups map to Tool Packs.

Pick this when:

You’re shipping an agent for your employees, not your customers.
Your security team requires SSO + SCIM and wants role-based access tied to IdP Groups.
You don’t want to embed Link or maintain a credential-management surface in your own product.

Read Context layer for employees.

Local development

You’re building. You want tools in Cursor or Claude Desktop without standing up a backend. Use the Merge CLI or the simplified MCP URL with your own login.

Pick this when:

You’re a solo developer prototyping an agent.
You’re testing a Connector or Tool Pack before wiring it into a production setup.
You want a personal agent for personal accounts (your GitHub, your Gmail) without involving an organization.

Read Local development.

Choosing

The two-question version: who is the end user, and who controls their identity?

Customer’s user, identity in your app’s database → Building an agent.
Your employee, identity in your IdP → Context layer for employees.
You, identity is just you → Local development.

If you’re not sure, start with Local development to feel out the surface, then move to Building an agent or the Context layer for employees once you know which shape your product is.