> This page is for Workforce. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Connect employee AI clients > Per-client connection details for employee AI clients: the Workforce MCP endpoint for tools in Claude, Claude Code, Cursor, Windsurf, and VS Code, and the Gateway base URL and key for models. **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](/merge-workforce/devices/overview) 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](/merge-workforce/rollout/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](/merge-workforce/rollout/tools). ## Connect to tools 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 client receives a scoped token. It renews that token on its own from then on. #### Claude (web & desktop) 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: 1. In Claude, go to **Organization settings → Connectors** 2. Click **Add**, hover over **Custom**, then select **Web** 3. 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: 1. Go to [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 2. Find the connector and click **Connect** 3. Sign in through SSO and complete your identity provider's steps 4. Confirm the selected tools, and the connector is ready to use #### Claude Code ```bash claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp ``` #### Cursor Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): ```json { "mcpServers": { "agent-handler": { "url": "https://ah-api.merge.dev/mcp" } } } ``` #### Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "agent-handler": { "serverUrl": "https://ah-api.merge.dev/mcp" } } } ``` #### VS Code Add to `.vscode/mcp.json` (workspace) or your user profile via the **MCP: Open User Configuration** command: ```json { "servers": { "agent-handler": { "type": "http", "url": "https://ah-api.merge.dev/mcp" } } } ``` #### Other MCP clients Most MCP clients accept the standard `mcpServers` JSON shape: ```json { "mcpServers": { "agent-handler": { "url": "https://ah-api.merge.dev/mcp" } } } ``` Check the client's docs for exact field names. Some use `serverUrl` instead of `url`, and some require a `type: "http"` field. Ask the assistant for a tool the employee's Group does not grant and the call fails. The ask lands in [Requests](/merge-workforce/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. | Input | Value | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base URL** | `https://api-gateway.merge.dev/v1/openai` for OpenAI-compatible clients, `https://api-gateway.merge.dev/v1/anthropic` for Claude Code and Claude Desktop | | **API key** | The employee's own Gateway key (see below), or a project API key the team already has | | **Model name** | `provider/model`, or `default_routing` to let the routing policy pick | 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](/merge-workforce/models/routing) rather than pinning one model in a config file the employee owns. > **A restricted Group needs a routing policy it can use** > > When a Group's [model access](/merge-workforce/models/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: | Source | When to use it | What the employee does | | ----------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Workforce console** | Any client, including Claude Desktop, Cursor, and Zed | Signs in to the console, opens **Get started**, chooses **Set it up myself** under Model routing, picks the client, and clicks **Get your personal key**. The page shows the key once and fills it into the steps for that client, along with the base URL | | **Desktop client** | Claude Code and Codex CLI on a managed fleet | Signs in from the menu bar; the client mints the key and offers **Connect Gateway** per client | | **[Workforce CLI](/merge-workforce/rollout/workforce-cli)** | Terminal users | `mfw login`, then `eval "$(mfw env)"` exports the key and base URL | 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. > **Console self-setup needs the employee view** > > 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](/merge-gateway/coding-agents/overview) have the exact configuration for each of the nine supported clients, at about five minutes apiece. For [Claude Desktop](/merge-gateway/coding-agents/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. > **ChatGPT desktop routes Work, not Chat** > > In the ChatGPT desktop app only the **Work** tab, which runs on Codex, reads the [Codex configuration](/merge-gateway/coding-agents/codex) 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](/merge-workforce/rollout/workforce-cli#pointing-an-ai-tool-at-the-credential), `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](/merge-workforce/rollout/overview).