Setup

Agent Handler for Employees

This page covers setup for employees. IT configures which tools each role can access; employees connect their AI client to a single MCP URL and authenticate through SSO.

Your identity provider manages users and Group memberships. Agent Handler maps those Groups to the tools they can access, which define what users in each Group are allowed to call. SCIM keeps them in sync: add someone to the Sales group in Okta, and Agent Handler grants them the tools that Sales has access to with no separate step on your end.

If you’re embedding an agent in a product (for customers or as an internal tool), see Building an agent instead. For a side-by-side comparison, see Use cases.

What you’re setting up

This setup gives you:

  • Identity provisioned through your identity provider via SCIM, so employees are added and removed automatically
  • Tools assigned to Groups, controlling which tools each team can access
  • A single MCP URL your employees can connect their AI clients to
  • Audit logging active, with exportable records for compliance reviews

Setup

Follow these steps to configure Agent Handler for employees. You can also follow the “Get started” guide in the application itself.

1

Enable SCIM in Agent Handler

Open the Provisioning tab in the Agent Handler dashboard. Before moving to your IdP, complete both of these:

  1. Generate a SCIM token, following SCIM provisioning. You’ll paste this token into your IdP in the next step.
  2. Set Default access. This is the tool access an employee gets before they’re assigned to a Group. Anyone not yet in a Group falls back to this setting. Leave it empty and those employees will see no tools in their AI client. See Managing tool access.
2

Configure SCIM in your IdP

In your identity provider (Okta, Azure AD, Google Workspace, or another SCIM provider), configure the Agent Handler SCIM application. All three of these happen in the same session:

  1. Enter the SCIM endpoint and token from the previous step.
  2. Assign employees to the Agent Handler SCIM application. Agent Handler creates their records as they come through.
  3. Push the Groups you’ll use for tool access: your existing Sales, Engineering, Finance groups, or whatever maps to roles in your org.

Sync timing varies by provider. Okta is near-real-time, while Azure AD runs on an approximately 40-minute default cycle.

3

Map Groups to tool access

In Agent Handler under Manage access → Group access, configure each Group with the following settings:

  • Tool access: assign Tool Packs or individual tools. Whatever you assign here is what members of this Group can call from their AI client (Claude, ChatGPT, Cursor, and other MCP clients).
  • Dashboard role: what members can do inside the Agent Handler dashboard.

Settings apply to everyone in the Group. If an employee belongs to multiple Groups, they get the most permissive access across all of them. See Managing tool access for how default access, Group access, and individual overrides layer together.

4

Share connection details with employees

There are two ways for employees to connect their AI clients with Agent Handler. Both authenticate through your identity provider and enforce the tool access you configured above.

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

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

On first connection, the client opens a browser for SSO. After the employee authenticates, they see a consent screen listing the tools their Group has been granted, and the AI client receives a scoped token.

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

Option B: Merge CLI

For employees working in CLI-based AI tools like Claude Code or Codex, the Merge CLI authenticates through the same identity provider flow.

$pipx install merge-api
$merge login

Then connect 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 admins control

  • Group-based access. Change a Group’s Tool Pack and every member’s access updates on the next call.
  • Direct assignment. Override the default tool access permissions on a per-employee basis.
  • Token lifecycle. Access tokens expire after an hour; refresh tokens rotate. Revoke individual tokens from the dashboard.
  • Audit Trail. Every tool call is logged with user, tool, arguments, and result. Exportable for SOC 2, ISO 27001, and other audit requirements.
  • Deprovisioning. Remove an employee from your identity provider or from the Agent Handler-bound Group and their tokens are revoked immediately.

What employees see

The first time an employee connects, they sign in through your identity provider and see a consent screen listing the tools their Group has been granted. After that, the AI client re-authenticates in the background.

If they ask the assistant to do something outside their allowed tools, say an Engineering employee asking for billing data, the call fails and the request appears in the Audit Trail. From the dashboard you can review it and approve access, decline it, or extend the employee’s tool set.

Common issues

  • Employee provisioned in your identity provider but not visible in Agent Handler. The SCIM sync may not have run yet. Okta is near-real-time; Azure AD defaults to a ~40-minute cycle. Check your identity provider’s provisioning log.
  • Employee can sign in, but the AI client shows no tools. Their Groups aren’t mapped to a Tool Pack. Open Manage access → Group access and assign one. If they’re not in any Group yet, also check that Default access is configured. See Managing tool access for additional details.
  • 403 error mid-conversation. The AI client will attempt to re-authorize automatically. If the tool is outside the employee’s allowed set, the admin dashboard shows a pending access request.
  • Token won’t refresh. Refresh tokens are revoked on deprovisioning. Confirm the employee is still active in the identity provider.

For more, see Troubleshooting.

Next

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