docs: add local server security guide#3072
Conversation
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.
|
@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. |
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.
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. |
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.