claude-code - 💡(How to fix) Fix [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

.