docs: add local server security guide - #3072
Conversation
github-actions
Bot
added
the
documentation
|
@PederHP - Hey, apologies for the delay, here's the first draft of the local server security doc we talked about doing on the MCP Dev Summit in NYC. This is the 1st take so feel free to suggest or even directly push on top of it, we can mix and match as we think it's best 👍 I would love your pass on it, i.e. does it match what we talked about, the sections order, the overall length, etc. |
No apology needed. This was as much on me as on you. Looks like a solid draft. I will read through it and give my thoughts. Two things I would like us to address in addition to the the threats you've covered:
I'll read it properly through and make some suggestions. But thank you so much for drafting this. |
| exposed to. | ||
|
|
||
| **If unsure**: install few servers, skim their tool descriptions once, and | ||
| favor a client that re-prompts when a tool definition changes. |
There was a problem hiding this comment.
is it within scope of this guide to include instructions on how to skim the tools and their descriptions? a vendor-neutral way would be to leverage MCP inspector. wdyt?
|
|
||
| A container is not an impenetrable boundary, but it removes the default | ||
| access to your environment, your files, and your keychain — which is what | ||
| the common attacks rely on. |
There was a problem hiding this comment.
It is correct that containers are not much of a security boundary other than isolation of resources. However, there are some levers that can increase security in containerized workloads:
- Seccomp profiles: limiting the number of system calls that the container can do can indeed reduce the attack vector.
- Using a Linux LSM: Some popular distributions provide an LSM (Linux Security Module) implementation for enhanced security. e.g. Ubuntu provides AppArmor to limit what resources the container can access, while Red Hat bases systems like Fedora provide SELinux. more often than not, it's a matter of enabling defaults.
these two can get you a very long way when running containers.
Cover the local machine threat model for MCP servers: provenance checks, process isolation, credential isolation, filesystem and network least privilege, and guidance for managing local servers across an organization.
A stdio client and server run as peers in one trust domain; neither the protocol nor the SDKs defend one against the other, and the transport is not a sandbox. Also add an org-section note on deploying centrally when machine-local access is not required.
Add two threats surfaced by ecosystem research: poisoned tool catalogs (tool poisoning, shadowing, rug pulls — definitions the model reads can hide directives and change after approval) and vulnerable-but-legitimate local components exploited by data they process. Add a section on treating tool definitions as untrusted input, note that localhost listeners are not an authentication boundary, pair version pinning with advisory-driven updates, extend registry caveats to curated catalogs, and add audit logging to the organization guidance and checklists.
Address review feedback: make explicit that the protocol cannot guarantee a server is or does what it promises — provenance tells you who you are trusting, not that the trust is warranted — and that SDKs assume full trust between stdio peers by design, leaving isolation to the host application and machine operator. Vetting reduces the odds of a bad trust decision; containment decides what it costs.
Follow the 2026-07-28 docs restructure: the guide now lives in the 2026-07-28 (default) and draft trees with per-version internal links, matching how the release process cuts new versions from draft.
92c71b7 to
af804de
Compare
The 2026-07-28 release deprecates the Roots feature (SEP-2577) in favor of passing directories through server configuration or tool parameters. Update the filesystem access guidance in both the 2026-07-28 and draft copies accordingly and generalize the cooperative-boundary warning to configuration-level allowlists.
3 participants
This adds a new tutorial page, Local Server Security
(
docs/tutorials/security/local-server-security.mdx), to the Security group,covering the machine-level threat model of running MCP servers locally.
Motivation and Context
The existing security docs cover the protocol threat model — OAuth flows,
confused deputy, session hijacking (
security_best_practices.mdx,authorization.mdx). None of them cover what happens on the machine itself:a local MCP server is an ordinary child process that inherits the user's
environment variables, filesystem access, and unrestricted network egress.
None of that is governed by the protocol.
This guide fills that gap with practical, vendor-neutral defaults:
and server share one trust domain — the transport is not a sandbox), and
five threats in scope (malicious server, overcollecting server, compromised
dependency, poisoned tool catalog — tool poisoning/shadowing/rug pulls —
and vulnerable-but-legitimate local components)
isolation, credential isolation, filesystem access, network egress — each
ending with a named "If unsure" default
fleet (approved sources, config inventory, incident response)
It complements SEP-1024 (client consent for one-click installs): the client
shows you the command, this guide covers what to check. Protocol-level
topics link out to the existing pages rather than restating them.
How Has This Been Tested?
npm run serve:docs— page renders correctly, nav entry appears underDevelop with MCP → Security
npm run preppasses clean (prettier, MDX comment check,mint broken-links,schema checks)
Breaking Changes
No.
Types of changes
Checklist
Additional context
This guide is an action item from the last MCP Dev Summit in NYC. The stdio
trust model section also gives a public-facing home to the stance the SDK
maintainers are converging on: the two stdio peers form a single trust
domain, and isolation is the deployment's responsibility, not the
transport's. Editorial
ground rules used throughout, so reviews can hold us to them: vendor-neutral
(patterns over products; where tools are named as examples, at least two
alternatives are given), prescriptive on principles with a menu of
implementations, and every section ends with a concrete default. A follow-up
blog post is planned once this lands.