Connect employee AI clients
Applies to: Merge Agent Handler and Merge Gateway
This is the page to send an employee. Tools and models are separate connections, and an employee can have one or both: an MCP endpoint for the tools their Group grants, and a Gateway base URL and key for the models it allows. Neither requires anything the employee has to request from you first.
On a fleet you manage, the desktop client mints the employee’s Gateway key and, once policy signing ships, writes both connections on the machine, so nothing here is needed. Use this page for the self-setup path, and for any client the desktop client does not reach. Roll out models covers which is which.
If the client is one an administrator can configure centrally, you may not need to send this page at all. Claude Code, Codex, and Gemini CLI can each receive the endpoint through their own enterprise policy layer, which also stops employees adding ungoverned servers beside it. See Roll out tools.
Connect to tools
Most MCP-capable AI clients accept a URL. Employees paste this one:
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 client receives a scoped token. It renews that token on its own from then on.
Claude (web & desktop)
Claude Code
Cursor
Windsurf
VS Code
Other MCP clients
Claude takes a one-time admin setup, then employees connect themselves.
Admin setup. An Owner or Primary Owner (Team or Enterprise plan) adds Workforce as an organization custom connector, once:
- In Claude, go to Organization settings → Connectors
- Click Add, hover over Custom, then select Web
- Paste the remote MCP server URL
https://ah-api.merge.dev/mcp, then click Add
Employee setup. Share these steps with employees on Claude desktop or cowork:
- Go to claude.ai/customize/connectors
- Find the connector and click Connect
- Sign in through SSO and complete your identity provider’s steps
- Confirm the selected tools, and the connector is ready to use
Ask the assistant for a tool the employee’s Group does not grant and the call fails. The ask lands in Requests for an admin to approve or decline.
Connect to models
Every AI client asks for the same three values. Point it at Gateway instead of the model provider and the provider key is replaced by a Gateway key.
Sending an Anthropic client to the OpenAI prefix is the most common setup mistake. default_routing is the value to prefer, because it leaves model choice with your routing policy rather than pinning one model in a config file the employee owns.
When a Group’s model access is limited to a list, Gateway keeps only the routing policy targets on that list. If none of the policy’s models are allowed, every default_routing request from that Group fails with a 403 before any model is tried. Give the Group a policy that includes at least one of its allowed models, or widen the list.
Where an employee gets their key
Employees do not have the Gateway dashboard, so the key never comes from an API keys page. It comes from one of three places, and each one attributes spend to the employee rather than to a shared team key:
Each Get your personal key click replaces the employee’s previous console key, so an employee setting up a second client pastes the same key rather than generating a new one.
The Get started page is shown to employees only when the employee view is enabled for your organization. If an employee signs in and sees no such page, ask Merge to turn it on before rollout.
Each client asks for those three values in a different place, from a settings pane to ~/.codex/config.toml. The per-client setup guides have the exact configuration for each of the nine supported clients, at about five minutes apiece. For Claude Desktop, the employee pastes the key and base URL into Developer → Configure Third-Party Inference, and Chat, Cowork, and the built-in Claude Code surface all route through Gateway.
In the ChatGPT desktop app only the Work tab, which runs on Codex, reads the Codex configuration that points at Gateway. The Chat tab has no base URL setting in the app or in ChatGPT Enterprise admin, so its conversations stay on OpenAI’s hosted models and never appear in your logs or budgets. Chat can still use your tools through the Workforce MCP connector.
On a machine set up with the Workforce CLI, eval "$(mfw env)" exports those values for Claude Code, Codex, and any OpenAI- or Anthropic-SDK client in one step, and mfw mcp --write .mcp.json writes the tools half.
Next
Confirm traffic is arriving and coverage is real with the verification steps in Roll out to your fleet.