Last updated: June 2026

Individual MCP setup is self-contained. Each engineer adds servers to their own config file, manages their own tokens, and maintains their own list of what's connected. This works well for one person. When a team adopts it, the problems from the previous chapters compound: credential sprawl, no audit trail, no access differentiation.

But there's a fifth problem that doesn't get enough attention: the deployment itself. Every new server requires every engineer to update their own config. When you add Pylon or Github or a new internal service, you're sending instructions to your whole team and hoping they follow them.

A shared gateway solves this differently. Admins register servers once in a central registry. Every team member connects to the gateway with a single endpoint. When a new server is added, every team member with the appropriate grant gets access automatically. Nobody touches their own config.

Solutions to consider

Per-engineer config management

The default. Everyone maintains their own Claude Desktop or Claude Code config manually, or follows a wiki page that lists the servers to add. This scales to small teams for a while. The failure modes: configs diverge, engineers miss updates, nobody knows what anyone else has connected. When you want to remove a server, you're sending instructions and hoping.

One related option worth being aware of: Anthropic recently released MCP tunnels (currently in beta), which solve a connectivity problem. They let Claude reach MCP servers inside a private network without opening inbound firewall ports, but they don't add tool-level access control, audit logging, or centralized credential management. If your main challenge is network connectivity rather than governance, tunnels are worth evaluating. If governance is the problem, they don't help much (for now, anyway).

Scripted config distribution

Some teams use a script or dotfiles repo to push a standard Claude Desktop config to all engineers. This is better: configs stay consistent, updates are centralized. The gaps: it still requires engineers to run the script, it doesn't handle per-user authentication (everyone gets the same config), and it doesn't give you any of the governance benefits (audit logging, tool-level access control) that a gateway provides.

Gateway with MDM deployment (our approach)

A central gateway endpoint with a single auth token per user, pushed automatically via MDM. No manual config steps for engineers, consistent across the team, and the gateway handles everything else: server registration, grants, audit logging, credentials. The tradeoff, of course, is that you need MDM infrastructure and a gateway to run.

Aptible's solution: shared gateway with MDM

The gateway sits between your Claude clients and your upstream MCP servers. From an engineer's perspective, they configure one endpoint and connect with one token. Everything else (which servers exist, which tools they can call, how credentials get managed) is handled centrally by whoever administers the gateway. The rest of this section covers how to set that up.

<aside> 🚧

SME Note: Please confirm: (1) Claude Desktop mobileconfig file path on macOS and whether Windows requires a different approach, and (2) whether the gateway URL pattern for customer deployments (https://<org-subdomain>.aptible.com/mcp) is correct and should be published.

</aside>

Building a server registry

The server registry is the foundation of org-wide deployment. Instead of each engineer managing their own list of servers, an admin registers servers once and the whole team gets access based on their grants.

Each server in the registry has:

• A name (used to namespace tool calls: notion_search, github_get_commit)

• A URL pointing to the upstream MCP server

• An auth type and credentials (bearer token, OAuth, or custom headers)

• An auth mode: shared (one org-wide credential) or personal (each user authenticates individually)

When a new server is added to the registry, no engineer config changes are required. The gateway discovers the server's tools automatically, and grants determine who can call them.

The multiplayer advantage: tool definitions are cached at the gateway level for shared-mode servers. This means you get one tool refresh cycle for the whole organization rather than N refreshes for N engineers. For personal-mode servers, each user's credential scopes the available tools independently.

Configuring Claude Desktop for your team

For MDM-managed deployment, Claude Desktop is configured via a mobileconfig profile using the com.anthropic.claudefordesktop payload type. The profile sets managedMcpServers to point at the gateway and uses a headersHelper script to supply per-user auth tokens rather than embedding them in the profile. This keeps credentials out of the MDM payload -- the helper script runs at connection time and returns the current token.

Here's the relevant portion of the profile (adapted for your deployment -- replace the gateway URL and credential helper path for your environment):

<key>managedMcpServers</key>
<string>[{
  "name": "your-gateway",
  "url": "<https://your-gateway-url/mcp>",
  "headersHelper": "/usr/local/bin/your-credential-helper",
  "headersHelperTtlSec": 180,
  "transport": "http"
}]</string>

The headersHelper is a script that outputs the Authorization header value. The gateway URL for Aptible-hosted deployments follows the pattern https://<org-subdomain>.aptible.com/mcp ; for example, https://c.aptible.com/mcp for Aptible's own team.

<aside> 🚧

SME Note: Please confirm the correct file path for the mobileconfig on macOS and whether Windows requires a different approach.

</aside>

The <user-token> is the engineer's individual token from the gateway: either a JWT from Aptible auth or a robot API key if the user is an agent. This is the only per-user value in the config; everything else is the same for every engineer on the team.

Configuring Claude Code for your team

Claude Code uses a separate mobileconfig profile (com.anthropic.claudecode payload type) and a managed MCP JSON file. The JSON file lives at /Library/Application Support/ClaudeCode/managed-mcp.json on macOS and is deployed via the MDM profile.

The managed MCP JSON format (adapt the URL and credential helper for your deployment):

{
  "mcpServers": {
    "your-gateway": {
      "type": "http",
      "url": "<https://your-gateway-url/mcp>",
      "headersHelper": "/usr/local/bin/your-credential-helper"
    }
  }
}

The mobileconfig profile also sets allowManagedMcpServersOnly: true, which is worth highlighting: it prevents engineers from adding their own direct MCP connections that bypass the gateway entirely. Without this, engineers could configure a direct connection to an upstream server and route around access controls and audit logging. This one flag closes a significant gap in org-wide governance.

MDM deployment: zero-configuration setup

At Aptible we deploy both profiles via Jamf. The profiles push to every team member's machine automatically; engineers connect to the right servers from the first time they open Claude Desktop or Claude Code. When we add a new server to the gateway registry, no profile update is required; the gateway handles server discovery. The profiles only need to change when the gateway URL or authentication approach changes.

Here's the Claude Code mobileconfig structure, showing the key governance fields:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "<http://www.apple.com/DTDs/PropertyList-1.0.dtd>">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>com.anthropic.claudecode</string>
      <key>PayloadDisplayName</key>
      <string>Claude Code Managed Profile</string>
      <!-- ... other PayloadIdentifier, PayloadUUID, PayloadVersion fields ... -->

      <!-- Restrict MCP to managed gateway only -->
      <key>allowManagedMcpServersOnly</key>
      <true/>

      <!-- Only allow connections to approved gateway URLs -->
      <key>allowedMcpServers</key>
      <array>
        <dict>
          <key>serverUrl</key>
          <string><https://your-gateway-url/*></string>
        </dict>
      </array>

      <!-- Credential helper for gateway auth -->
      <key>apiKeyHelper</key>
      <string>/usr/local/bin/your-credential-helper</string>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadScope</key>
  <string>User</string>
</dict>
</plist>

For teams using other MDM solutions (Microsoft Intune, Mosyle, etc.), the mobileconfig format is the same; it's a standard Apple configuration profile. The payload types (com.anthropic.claudefordesktop and com.anthropic.claudecode) are Anthropic-specific but the profile structure is standard.

What MDM deployment enables: new engineers get gateway access on day one without any manual setup. Engineers who leave have their access revoked at the identity layer; remove their gateway token, and their Claude Desktop and Claude Code stop connecting to your servers. No config cleanup required.

Where robots fit in org-wide deployment

Robots (described in Agent identity and robot users) are provisioned through the same gateway that your human users connect to. The difference is how they authenticate: a robot API key (aptk-...) instead of a user JWT, configured wherever the agent runs: a CI environment variable, a container secret, a serverless function configuration.

Robots don't go through MDM. They're provisioned individually when the agent workflow is set up, and their credentials are managed as secrets in whatever infrastructure runs the agent. The gateway treats them identically to human users for grant resolution and audit logging, but with an empty email field that distinguishes them in the log.

How you could structure this for your team

The most common starting point: create one gateway endpoint, register your highest-traffic servers first, and push the config to engineers via your existing MDM solution or a shared dotfiles approach. You don't need to migrate every server at once. Engineers can have the gateway configured alongside any direct server connections they currently use, and you can migrate gradually.

The main decision to make early is how you handle per-user authentication for personal-mode servers. OAuth is the cleanest approach: users connect to personal-mode servers (GitHub, Notion, Shortcut) by clicking "authorize" in the gateway UI, and their credentials are stored centrally. This is significantly better than asking every engineer to find and paste their personal token into a config file.

For shared-mode servers (Snowflake, internal databases, analytics tools), decide upfront whether you want a service account or individual credentials. Shared credentials are easier to manage; individual credentials give you per-user attribution in the upstream service's logs alongside the gateway's audit trail.

FAQs

Do engineers need to change anything when a new server is added?

No, when a server is added to the registry, engineers with the appropriate grant see the new tools automatically on their next connection. This is the primary operational advantage of a shared gateway over per-engineer config management.

What happens when an engineer leaves?

Revoke their gateway token. Their Claude Desktop and Claude Code stop returning tools from the gateway immediately (within the 120-second auth cache window). You don't need to update their local config or chase down shared credentials they may have had.

Does this work with Claude.ai or other clients?

The gateway is a standard MCP-over-HTTP endpoint, so any MCP client that supports streamable HTTP transport and custom auth headers can connect to it. Claude Desktop and Claude Code are the primary clients for most teams. Other clients may have different config formats.

Can I run multiple gateway instances?

Yes. For teams that need environment separation (a staging gateway with test data access, a production gateway with restricted permissions), separate gateway instances with separate server registries and grant configurations are the right approach. Engineers configure both, and the environment-specific token determines which gateway they're connecting to.

What if some engineers have servers the gateway doesn't cover yet?

They can keep direct connections for those servers while the gateway is used for everything else. There's no requirement to migrate everything at once. The audit trail and access controls only apply to what flows through the gateway, so migrating servers incrementally is a reasonable approach, it's just worth being explicit about what is and isn't covered during the transition.

Next steps

If you need to understand how tool grants work before deploying: Tool-level access control: how roles, servers, and grants are structured

If you're provisioning robots alongside human users: Agent identity and robot users: how robots authenticate and how they fit into the same gateway your team uses

If you're in a regulated industry and need audit coverage from day one: Audit logging for MCP tool calls: what gets recorded automatically once the gateway is in place

Aptible MCP Gateway gives engineering teams tool-level access control, audit logging, and centralized credential management for MCP without building the proxy infrastructure yourself. Deployed alongside Aptible AI Gateway, it covers both LLM and tool call governance in one place. Join the MCP Gateway waitlist →