Internal agent product

Setup your internal agent product

End-to-end path for enterprise customers to go from zero to users running tools via the simplified MCP URL.

This guide walks enterprise customers through setting up Merge Agent Handler for an internal agent product — an agent used by your own team that connects to your company’s internal tools and systems. Setup is managed end-to-end via SCIM and your identity provider.

1

Enable SCIM in Agent Handler

Go to Settings → SCIM in the Agent Handler dashboard. Here you’ll configure default access levels for new users and generate a SCIM token. Copy this token because you’ll use it to connect your identity provider (Okta, Azure AD, etc.) to Agent Handler.

2

Provision users in your identity provider

In your IdP, assign users to the Agent Handler SCIM application. When a user is provisioned, Agent Handler automatically creates two things: a dashboard User and a linked Registered User. The Registered User is the identity used for tool execution. It’s created behind the scenes and never needs to be referenced directly.

3

Push IdP groups

In your IdP, push or add the groups you want to use for tool access management (e.g., “Engineering”, “Sales”, “Product”). These groups will sync to Agent Handler and serve as the basis for assigning tools at scale.

4

Configure group-to-tool mapping

Back in the Agent Handler dashboard under SCIM settings, configure each IdP group’s access. For each group, you can set:

  • Dashboard role — admin or member permissions within Agent Handler.
  • Tool access — assign Tool Packs or individual tools that members of the group should have access to.

These settings are applied to every provisioned user who belongs to that group. If a user is in multiple groups, their tool lists merge into one effective set.

5

Users are ready

Every SCIM-provisioned user now has a Registered User linked to their account with the tools you configured. They can only execute tools through their own Registered User — scoped to the access you’ve defined. No shared keys, no manual wiring.

6

Users connect via the simplified MCP URL

Your team members add a single URL to their MCP client (Claude Code, Cursor, etc.):

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

On first connection, the client kicks off the OAuth flow automatically. The user authenticates in the browser, sees a consent screen showing the tools you’ve approved for them, and receives a scoped token. From there, their agent can call any authorized tool.

Admin tool management

Admins control which tools each user can access through two mechanisms, both configured in the dashboard:

  • Tool Packs — reusable templates assigned to users or groups. Ideal for bulk operations (e.g., “everyone on Sales gets these 10 tools”). Assigning a Tool Pack writes per-user tool access under the hood.
  • Direct assignment — edit a specific user’s tool list for exceptions and one-offs.

When a user has tools from multiple Tool Packs, the system merges them into one effective list. The consent screen and token validation always operate against this merged list — Tool Packs are never referenced at runtime.

Deprovisioning

When a user is removed via SCIM, Agent Handler immediately deactivates the User, deletes the linked Registered User, and invalidates all active tokens. Admins can also revoke individual tokens from the dashboard at any time.

Scoped access & tool authorization

Scope management is based on tools. Users can select which tools they want to use based on the subset of tools admin has restricted them to.

Scope escalation

When an agent calls a tool outside the token’s current scope, the server returns a 403 with the missing tool name. What happens next depends on the user’s allowed tool list:

  • Tool is within the user’s ceiling but wasn’t selected at auth time: the client initiates a new OAuth flow so the user can grant permission for the additional scope.
  • Tool is outside the user’s allowed list: the 403 triggers a notification to the org admin, who can approve or deny the request from the dashboard. Once approved, the user re-authenticates to receive an expanded token.

Token lifecycle

SettingDefault
Access token lifetime1 hour
Refresh tokenLong-lived, with rotation
Token expirationConfigurable in dashboard settings

Refresh tokens extend sessions without requiring re-authentication. Admins can revoke individual tokens from the dashboard. merge tools add/remove re-issues tokens without requiring a new login.

Quick reference

Enterprise admin checklist

  1. Settings → SCIM — configure default access, generate SCIM API key
  2. IdP — provision users to Agent Handler via SCIM
  3. IdP — push groups you want to manage tool access for
  4. Dashboard → SCIM settings — map IdP groups to roles and Tool Packs
  5. Verify — provisioned users have linked Registered Users with scoped tool access
  6. Share the URL — users add https://ah-api.merge.dev/mcp to their MCP client and authenticate

Individual user checklist

  1. Point your MCP client to https://ah-api.merge.dev/mcp
  2. Complete the OAuth flow when prompted in the browser
  3. Select your desired tool scopes on the consent screen
  4. Start making MCP calls with your scoped token

Head over to ah.merge.dev to start supercharging your team’s AI work!