What does Claude Code's managedMcpServers setting do?

Added in Claude Code v2.1.259 (2 September 2026), it's a managed setting that lets an organization provide HTTP and SSE MCP servers to every user, using the same entry shape as a project's .mcp.json file. Unlike managed-mcp.json, it's a setting deployed through ordinary managed settings channels rather than a separate file that needs MDM or fleet-management tooling to place on disk.

Why does managedMcpServers only support HTTP and SSE servers?

Per the v2.1.259 changelog, an entry that names a command to run is skipped. A stdio server entry names a local executable or script to launch, which only makes sense if that binary already exists on every user's machine; a remote HTTP or SSE server just needs a URL, which is safe to push to any machine regardless of what's installed on it.

How is managedMcpServers different from managed-mcp.json?

managed-mcp.json is a file deployed to a fixed system path that gives exclusive control: once it's present, users can't add, modify, or use any other MCP server. It requires MDM, GPO, or another fleet-management tool with administrator privileges to place, and can't be set through server-managed settings. managedMcpServers is a setting inside the managed settings you already deploy through server-managed settings, managed-settings.json, an MDM profile, or the registry, alongside every other managed key.

Does managedMcpServers stop users from adding their own MCP servers?

Nothing in the v2.1.259 changelog entry says it does. Pair it with allowedMcpServers and allowManagedMcpServersOnly, or deploy managed-mcp.json instead, if you need to exclude servers users add themselves rather than just provision servers everyone gets.

What entry shape does managedMcpServers use?

The changelog says it uses the same entry shape as .mcp.json. For a remote server, that shape is an object with a type of http or sse and a url, the same shape Claude Code writes when you run claude mcp add --transport http against a project.

managedMcpServers: Claude Code's New MCP Setting

A third way to hand every user an MCP server

Anthropic keeps shipping incremental controls at the edges of Claude Code's MCP system rather than rethinking the whole thing at once, and this release is a good example: a narrow, specific addition that closes a real gap in how organizations distribute internal tools rather than a sweeping redesign.

Claude Code already had two separate, well-established ways for an organization to control which MCP servers its users can reach: managed-mcp.json, a file deployed to a fixed system path that takes exclusive control, and allowedMcpServers / deniedMcpServers, settings that filter what users add themselves without providing anything on their own. Neither one is quite "just give every user this server, no filesystem deployment required." managedMcpServers, added in Claude Code v2.1.259 (2 September 2026), fills that specific gap.

Per the changelog: "Added managedMcpServers managed setting: organizations can provide HTTP/SSE MCP servers to every user (same entry shape as .mcp.json); entries that name a command to run are skipped."

What it does

managedMcpServers is a managed setting, which means it's deployed the same way as any other key in managed settings: server-managed settings, a managed-settings.json file, an MDM profile, or the Windows registry. That's the detail worth sitting with, because it's what makes this genuinely different from managed-mcp.json, which is not a setting at all but a separate file placed at a fixed system path (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux, C:\Program Files\ClaudeCode\ on Windows) that Claude Code's own managed MCP documentation states explicitly "cannot be set through server-managed settings."

If your organization already has a managed settings pipeline for other keys, permission rules, environment variables, whatever else you push through server-managed settings, managedMcpServers lets you add MCP server provisioning to that same pipeline instead of standing up separate MDM tooling just to deploy a file.

Why only HTTP and SSE

The changelog is specific: "entries that name a command to run are skipped." An MCP server entry comes in two shapes, a command entry that launches a local process (a stdio server) or a type/url entry that connects to a remote endpoint (an HTTP or SSE server). A command entry only works if the named executable, npx, python, a compiled binary, actually exists at that path on the machine running it. Pushing a stdio server entry through a managed setting that reaches every user's machine, with no guarantee about what's installed there, would fail unpredictably depending on each machine's own setup.

A remote server has no such dependency. A url pointing at an HTTP or SSE endpoint works the same way regardless of what's installed locally, which is exactly the property you want from something distributed centrally to a fleet of machines you don't individually provision. Skipping command entries rather than erroring on them means a mixed list, someone accidentally copying a stdio entry from a personal .mcp.json into the managed setting, degrades gracefully instead of breaking the whole deployment.

The entry shape

The changelog says managedMcpServers uses "the same entry shape as .mcp.json." Claude Code's own MCP documentation shows exactly what that shape looks like for a remote server, the kind this setting actually accepts:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

That's the same object Claude Code writes to a project's .mcp.json when you run claude mcp add --transport http shared-server https://example.com/mcp with project scope. An sse entry follows the same pattern with "type": "sse" in place of "http". Because the changelog frames managedMcpServers as reusing this exact shape rather than inventing a new one, an entry your team already uses in a project's .mcp.json for a remote server should translate directly into the managed setting without reformatting, aside from wherever the setting nests it in your managed settings file.

How it compares to the other two mechanisms

	`managed-mcp.json`	`allowedMcpServers` / `deniedMcpServers`	`managedMcpServers`
What it does	Replaces the server list entirely; exclusive control	Filters servers users configure themselves	Provisions servers directly to every user
Server types	Any, including stdio (`command`) servers	Filters any type by URL, command, or name	HTTP and SSE only; `command` entries are skipped
Where it lives	A file at a fixed system path	Any settings scope, enforced from a managed source	A managed setting, deployed like any other managed key
Deployment mechanism	MDM, GPO, or fleet management with administrator privileges	Server-managed settings, `managed-settings.json`, MDM profile, or registry	Same managed settings channels as `allowedMcpServers`
Stops users adding their own servers	Yes, entirely	Only servers that fail the allowlist or hit the denylist	Not stated in the changelog; likely additive rather than exclusive

The practical difference from managed-mcp.json is deployment friction. managed-mcp.json needs a file placed on every machine through fleet-management tooling separate from your settings pipeline, and Claude Code's own documentation is explicit that it can't be delivered through server-managed settings at all. managedMcpServers needs nothing beyond whatever you already use to deploy managed settings. For an organization whose managed settings already reach every developer, that's meaningfully less infrastructure to stand up just to give everyone a shared connector.

The practical difference from allowedMcpServers is intent. An allowlist assumes users are adding their own servers and you're constraining which ones pass; it provisions nothing on its own. managedMcpServers provisions the server itself, so a user gets it without having to know it exists or run claude mcp add themselves.

A note on choosing HTTP over SSE

Claude Code's own MCP documentation flags that "the SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available." That guidance applies just as much to what you put in managedMcpServers as it does to a server you'd add yourself with claude mcp add. Since this setting only accepts remote servers in the first place, type: "http" is the entry to reach for whenever the service you're provisioning documents an HTTP endpoint; save type: "sse" for the servers that genuinely still expose only an SSE endpoint and nothing else. If a remote server's endpoint accepts the MCP specification's streamable-http terminology in its own documentation, Claude Code reads that as an alias for "type": "http", so configuration copied straight from a server's own docs works without translation.

Watching what actually gets used

Once you've pushed a server through managedMcpServers, the natural follow-up question is whether anyone is actually calling it. Claude Code's monitoring documentation covers exactly that, independent of how the server was provisioned: with OpenTelemetry export configured and OTEL_LOG_TOOL_DETAILS=1 set, Claude Code records which MCP servers and tools users invoke, so you can aggregate that data in your collector to see whether a centrally provisioned server is earning its place or going unused. That's worth setting up alongside a managedMcpServers rollout rather than after the fact, since it's the only way to tell a genuinely adopted internal connector from one nobody's session ever actually calls.

What isn't confirmed yet

Claude Code's settings reference and managed MCP documentation hadn't published a dedicated section for managedMcpServers as of this writing, so several practical questions aren't independently answerable from a primary source beyond the changelog line itself:

Whether servers from managedMcpServers are additive (users keep their own servers alongside them) or interact with allowManagedMcpServersOnly the way allowedMcpServers entries do
Whether a managedMcpServers entry appears in /mcp the same way a project-scoped or plugin-provided server does, and whether it's labelled managed
Whether deniedMcpServers can block a server that managedMcpServers provisions, the way it can block a managed-mcp.json server

Until Anthropic's own reference documents these, treat the changelog's one-line description as the confirmed behaviour and verify anything beyond it in your own deployment before relying on it for a security boundary. This is the same caution worth applying to any freshly shipped setting: a changelog entry tells you a feature exists and roughly what it does, not every edge case in how it interacts with the rest of the permission system.

A worked example

Say your organization runs an internal MCP server that wraps your incident-management API, and you want every developer's Claude Code session to have it available without asking each of them to run claude mcp add individually. In your managed settings source, alongside whatever other managed keys you already deploy:

{
  "managedMcpServers": {
    "incident-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com/incidents"
    }
  }
}

Deploy that through server-managed settings, managed-settings.json, your MDM profile, or the registry, whichever channel already reaches your fleet, and every user's session picks up the incident-api server without a separate file needing to land on their machine first.

If someone accidentally pastes a stdio entry into the same block, say a command pointing at a local script that only exists on the admin's own laptop, Claude Code skips that entry rather than failing the whole deployment, per the changelog's stated behaviour, though the exact skip mechanics (a warning shown to the user, a log entry, silent omission) aren't detailed in what's published so far.

Troubleshooting

A server I put in managedMcpServers never shows up in a session. Confirm it's a type: "http" or type: "sse" entry with a url, not a command entry. Command entries are skipped by design. Also confirm the managed settings source carrying it is actually reaching the session; managed settings have their own precedence rules across server-managed settings, managed-settings.json, MDM, and the registry.

I need to stop users from adding servers of their own alongside the managed ones. managedMcpServers on its own isn't documented as doing that. Pair it with allowedMcpServers and allowManagedMcpServersOnly to lock the allowlist to managed sources, or use managed-mcp.json if you need the stronger, exclusive-control guarantee that file provides.

I need to provision a stdio (local command) server to every user, not just HTTP or SSE. managedMcpServers doesn't support that; it skips command entries specifically because they depend on a local executable that isn't guaranteed to exist on every machine. Use managed-mcp.json for a fixed server set that includes stdio servers, accepting the heavier MDM-based deployment that requires.

The setting has no effect at all. Confirm your Claude Code version with claude --version; managedMcpServers requires v2.1.259 or later, released 2 September 2026, and earlier versions won't recognize the key.

Where this fits

For the full range of MCP access controls, including when to reach for managed-mcp.json versus an allowlist, see Claude Code's own managed MCP configuration guide. For a roundup of MCP servers worth connecting in the first place, see the best MCP servers for developers. For the broader distinction between an MCP server and an Agent Skill, which solve adjacent but different problems, see Agent Skills vs MCP. Browse Claude Code's current settings and install paths at getclaudeskills.com/platforms/claude-code.

Claude Code's managedMcpServers Setting Explained