Setup

Context layer for employees

Set up Agent Handler for employee use - SSO, Group-based tool access, full audit, managed through the IdP you already operate.

Agent Handler is the access-control layer for employee AI. Your workforce uses the AI assistant of their choice - ChatGPT, Claude, Cursor, any MCP-compatible client - and you decide which enterprise tools they can reach from inside it, scoped to their role and governed through your existing identity stack.

There’s a clean split: your IdP owns users and Group memberships; Agent Handler owns the mapping from Groups to tool access. SCIM syncs users and Groups in automatically - no separate user database for IT to maintain - and you assign Tool Packs to those Groups inside Agent Handler. Employees sign in once through SSO; their AI assistant inherits a token scoped to the tools their Group has been granted. Every call is captured in the Audit Trail.

If you’re shipping an AI product to your customers rather than enabling your employees, see Building an agent instead. For a side-by-side, see Use cases.

What you’re setting up

By the end of this guide:

  • Identity flows from your IdP via SCIM. Adding an employee provisions their access; removing them revokes it.
  • Authorization maps IdP Groups to tool sets. Sales gets one Tool Pack, Engineering another, Finance a third.
  • Connection is a single MCP URL employees paste into their AI client. First connect routes through SSO.
  • Audit records every tool call - who, what, when, with what arguments. Exportable for compliance.

You manage the policy in Agent Handler. Employees only see their AI assistant connected to the right tools.

Technical surface: an OAuth-authenticated MCP server at https://ah-api.merge.dev/mcp. Employees configure their AI client to use the URL; the server authenticates them through your IdP and issues a scoped token.

Setup

1

Enable SCIM in Agent Handler

Open Settings → SCIM in the Agent Handler dashboard. Configure default access for newly-provisioned employees and generate a SCIM token. You’ll paste this token into your IdP in the next step.

2

Provision employees through your IdP

In your IdP (Okta, Azure AD, Google Workspace, others), assign employees to the Agent Handler SCIM application. As they’re provisioned, Agent Handler creates the records it needs internally - you don’t manage these directly.

3

Push IdP Groups

Push the Groups you’ll use for tool access - your existing “Sales”, “Engineering”, “Finance” Groups, or whatever maps to roles in your org. These sync into Agent Handler and become the unit of authorization.

4

Map Groups to tools

Back in Agent Handler under SCIM → Group mappings, configure each Group’s access:

  • Dashboard role - admin or member inside Agent Handler.
  • Tool access - assign Tool Packs (bundles of tools) or individual tools.

Settings apply to every employee in the Group. Members of multiple Groups get the union of their tool sets.

5

Share connection details with employees

Two ways for employees to connect their AI client. Both go through your IdP and respect the tool access you mapped above.

Option A - MCP URL (recommended)

Most MCP-capable AI clients accept a URL. Employees paste this one:

https://ah-api.merge.dev/mcp

On first connection, the client opens the browser for SSO. After authenticating, the employee sees a consent screen showing the tools their Group has been granted, and the AI assistant gets a scoped token. From then on, the connection is transparent.

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

Option B - Merge CLI

For employees whose AI workflow is command-line driven (Claude Code, Codex, similar), the Merge CLI routes through the same IdP-backed authentication.

$pipx install merge-api
$merge login

Then connect the CLI to the 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.

What employees see

The first time an employee connects their AI client, they sign in through your IdP and approve the tools their Group has been granted. After that, their AI assistant calls those tools without further interaction.

If they ask the assistant to do something outside their tool set - say, an Engineering employee asks for billing data - the call returns an error and a violation entry in the Audit Trail. From the dashboard, you can review the request and approve, decline, or extend the employee’s access.

What you control

  • Group-based access. Change a Group’s Tool Pack and every member’s effective access updates on the next call.
  • Direct assignment. Override per employee for exceptions and one-offs.
  • Token lifecycle. One-hour access tokens with rotating refresh tokens. Revoke individual tokens from the dashboard at any time.
  • Audit Trail. Every tool call - user, tool, arguments, result - is captured. Exportable for SOC 2, ISO 27001, and similar reviews.
  • Deprovisioning. Remove an employee from the IdP, or from the Agent Handler-bound Group, and their tokens are revoked immediately.

Common issues

  • Employee provisioned in IdP but not visible in Agent Handler. SCIM sync hasn’t run yet. Okta is near-real-time; Azure AD runs every ~40 minutes by default. Check the IdP’s sync log.
  • Employee can sign in but the AI assistant sees no tools. Their IdP Groups aren’t mapped to a Tool Pack. Open Settings → SCIM → Group mappings and assign.
  • 403 mid-conversation on a tool. The AI client should auto-retry through OAuth to grant the missing scope. If the missing tool is outside the employee’s allowed set, an admin gets a request notification.
  • Token doesn’t refresh. Refresh tokens are revoked when an employee is deprovisioned. Confirm the employee is still active in the IdP.

For more, see Troubleshooting.

Next

Head to ah.merge.dev to start the SCIM setup, or read Tool Packs for how to shape what each Group can call.