@@ −73 +73 @@
(Configuration example preserved)
−## Security and agent safety (updated)
+## Security and agent safety (updated Apr 26, 2026)
−MCP servers often expose sensitive operations and data. Design for defense-in-depth and assume adversarial inputs. Practical, concrete recommendations (aligned with recent industry guidance and agent runtime updates):
+MCP servers often expose sensitive operations and data. Design for defense-in-depth and assume adversarial inputs. The following are concrete, research-backed controls and patterns (sources: MCP spec, reference servers repo, and recent industry guidance on agent runtimes and prompt-injection mitigation).
+Mandatory controls
- Minimize privileges: give each session and tool the least privilege required. Implement role-based checks and scope-scoped tokens; prefer separate service accounts for high-risk tools.
−- Constrain risky actions: treat network-accessing, filesystem, and destructive tools as high-risk. Require explicit session-level approval for such tools (incremental consent) and require confirmation steps for irreversible actions.
- Validate inputs and outputs: perform strict schema validation server-side and sanitize outputs before returning to the client. Log validation failures and surface them as structured errors. Use strong runtime validators (Zod, JSON Schema validators) and fail closed on unexpected input.
- Limit sensitive data exposure: redact or truncate secrets in resources and notifications; never embed credentials in tool descriptions or resource payloads.
+- Audit trails: record who invoked what, sessionId, toolName, effective scopes, and redacted parameter hashes. Store immutable audit events for compliance and forensic review.
+
+High-risk tool patterns
+- Constrain risky actions: treat network-accessing, filesystem, and destructive tools as high-risk. Require explicit session-level approval for such tools (incremental consent) and require confirmation steps for irreversible actions.
+- Sandbox untrusted code: if tools execute arbitrary code, run them in isolated containers or WASM sandboxes with strict syscall and network policies; log all side effects and enforce resource limits.
+- Use short-lived tokens and JWKS rotation: validate JWTs (aud/iss/exp), support JWKS key rotation, and prefer short session lifetimes. For long-lived integrations, use server-side refresh flows rather than persistent bearer tokens.
+
+Operational mitigations
+- Progress, timeouts, and cancellations: long-running or stateful operations should report progress via notifications and allow cancelation tokens; do not block JSON-RPC request threads for extended durations.
+- Incremental consent and WWW-Authenticate flows: follow the spec's incremental consent pattern for high-risk tools; expose clear UI affordances for granting per-session scopes and record consent artifacts in audit logs.
+- Prompt-injection hardening: prefer deterministic, validated tool APIs over free-text execution. Treat tool descriptions and resource content as untrusted until validated; design the contract so a successful prompt-injection has minimal impact (e.g., read-only views with limited data).
−- Use session consent and audit logs: record which agent/session invoked which tool, parameter values (redacted), and outputs returned. Store immutable audit events for compliance and post-hoc review.
+- Runtime sandboxing and isolation: follow emerging agent runtime patterns (see OpenAI Agents SDK updates) to sandbox tool execution where possible — run untrusted invocations in isolated processes, containers, or language sandboxes and enforce strict I/O policies.
−- Progress and timeouts: long-running or stateful operations should report progress via notifications and allow cancelation tokens; do not block JSON-RPC request threads for extended durations.
−- Prompt-injection mitigation: prefer deterministic, validated tool APIs over free-text execution. Never interpret tool descriptions or resource content as executable instructions without strict validation. Design the client-server contract so a successful prompt injection yields only limited impact (e.g., read-only view with minimal derivable secrets).
−- Runtime sandboxing and isolation: follow emerging agent runtime patterns (see OpenAI Agents SDK updates) to sandbox tool execution where possible — run untrusted tool invocations in isolated processes, containers, or language sandboxes and enforce strict I/O policies.
−- Incremental consent and WWW-Authenticate flows: implement the spec's incremental consent pattern for high-risk tools and expose clear UI affordances for granting per-session scopes; record consent artifacts in audit logs.
−- Explicit OIDC discovery: when supporting external authorization servers, implement OpenID Connect Discovery (OIDC Discovery 1.0), validate issued JWTs (aud/iss/exp), and support JWKS rotation. Use short-lived session tokens and server-side refresh flows for long-lived integrations.
Implementation notes and concrete controls:
+- Authentication: support OIDC discovery (OpenID Connect Discovery 1.0) for authorization server configuration where applicable; validate JWTs, verify aud/iss/exp, and support rotation of JWKS keys. (MCP spec changelog and SEPs document OIDC discovery support.)
+- Scopes and fine-grained authorization: model tool capabilities as OAuth2-like scopes and map them to RBAC roles on the server. Use short-lived session tokens and refreshable authorization for long-lived integrations.
−- Authentication: support OIDC discovery (OpenID Connect Discovery 1.0) for authorization server configuration where applicable; validate JWTs, verify aud/iss/exp, and support rotation of JWKS keys.
+- Auditability: emit structured audit events for every tool invocation and store them in an append-only store when possible.
−- Scopes and fine-grained authorization: model tool capabilities as OAuth2-like scopes and map them to RBAC roles on the server. Use short-lived tokens for sessions and refreshable authorization for long-lived integrations.
−- Sandbox untrusted code: if tools can execute code, run them in minimal container sandboxes or language-level sandboxes (e.g., WASM runtimes) with strict syscall and network policies; log all side effects.
−- Auditability: emit structured audit events for every tool invocation with sessionId, toolName, effective scopes, and redacted parameter hashes. Store these in a write-once append-only store when possible.
+References informing this section:
+- MCP specification (security and transports)
+- Reference servers repo (examples for sandboxing and tool patterns)
−References for these patterns include industry guidance on prompt injection and agent runtimes (see OpenAI links in References) and the MCP changelog and servers repo for implementation examples.
