[DOCS] governance and security guidance for MCP server adoption in teams

Documentation Type

Other

Documentation Location

_No response_

Section/Topic

MCP servers

Current Documentation

Summary

The MCP documentation in Claude Code covers single-developer setup well,
but there is no guidance for teams adopting MCP at scale. As Claude Code
moves from individual licenses to engineering-team adoption, the gaps in
shared-token, audit trail, and access control patterns become operational
problems.

This issue proposes adding a "MCP for Teams" section to the documentation
covering governance patterns that are currently undocumented.

The four gaps in current docs

1. Shared workspace tokens

The current MCP configuration model assumes one identity per machine.
When a team shares an MCP server (especially remote/HTTP servers), the
documentation does not address:

• How teams should manage credential rotation when a member leaves
• Whether per-user tokens are a supported pattern
• How to attribute tool calls to individual team members in shared

configurations

2. Audit trail expectations

The MCP protocol logs tools/call at the transport level, but there is
no documented pattern for:

• Capturing tools/call with member attribution in team deployments
• Retention recommendations for compliance scenarios
• Required fields for forensic-grade audit (caller identity, tool name,

timestamp, status, latency)

3. Local stdio servers in team contexts

Most MCP servers in the registry run as local stdio processes via npx.
The documentation does not address:

• How to share stdio-based servers across a team
• Offboarding patterns when a team member leaves
• Whether stdio is recommended for production team usage at all

4. Tool-level access control

The protocol supports tool discovery (tools/list) and invocation
(tools/call), but there is no documented pattern for:

• Restricting which tools a specific user can call
• Allowlist enforcement at the protocol vs application layer
• Whether allowlists should be implemented in the MCP server itself or

in an intermediate gateway

Why this matters now

Claude Code is moving into engineering teams that use MCP servers for
real production access — databases, code repositories, internal APIs.
Without documented guidance on the four points above, teams either:

1. Use shared tokens and accept the security gap
2. Avoid MCP for sensitive use cases (losing the productivity benefit)
3. Build custom governance infrastructure internally

Option 3 is happening already — there are at least three open-source
gateway projects, and at least one commercial governance platform
(MCPNest, which I've built and run at mcpnest.io). But the patterns
should be documented in the official MCP spec, not just rediscovered
by each team.

Proposed documentation additions

A "MCP for Teams" section covering:

• Identity model: per-user tokens vs shared tokens, with tradeoffs
• Recommended audit log schema (suggested fields: workspace_id,

member_id, tool_name, latency_ms, status)

• When to use local stdio vs hosted HTTP servers
• Tool allowlist patterns (centralised gateway vs server-side enforcement)
• Offboarding checklist for MCP access

I'm happy to contribute a draft of this documentation if useful. The
patterns above are not theoretical — they reflect what we've seen
building governance infrastructure for MCP at MCPNest, working with
engineering teams that have already hit these issues in production.

Context

I'm Ricardo Rodrigues, Platform Engineer at a financial institution in
Portugal and founder of MCPNest (https://mcpnest.io), an enterprise
governance layer for MCP servers. I'm not posting this to promote
MCPNest — I'm posting it because the documentation gap is real, and
addressing it in the official docs would benefit the entire MCP
ecosystem, regardless of which governance implementation teams choose.

What's Wrong or Missing?

.

Suggested Improvement

.

Impact

High - Prevents users from using a feature

Additional Context

.