Abstract

This SEP proposes the addition of a new secretHint annotation to the Model Context Protocol (MCP) specification. This hint explicitly marks whether the return value of a tool may contain sensitive information. MCP clients can then take extra precautions, such as restricting display, limiting logging, or enforcing stricter handling. By default, secretHint should be considered false unless explicitly marked as true.

Summary

The proposal introduces secretHint for tools within MCP. This communicates that a tool's output may contain sensitive data (e.g., personal information, credentials, or confidential business details). With this hint, MCP clients can implement protective measures to prevent unintended disclosure or mishandling of secrets.

Motivation

While existing annotations describe tool behavior (e.g., destructive, openWorld, readOnly), there is no explicit way to indicate that a tool’s return values may contain sensitive information.

Without this annotation:

Clients may log or display sensitive data without warning.

Developers and users lack a standard mechanism for signaling extra caution.

Security best practices depend on ad-hoc documentation instead of explicit protocol-level signals.

The secretHint provides a consistent and visible way to mark tools whose outputs require careful handling.

Proposal

Extend the ToolAnnotations interface with a new optional field:

interface ToolAnnotations {
  destructiveHint?: boolean
  idempotentHint?: boolean
  openWorldHint?: boolean
  readOnlyHint?: boolean
  title?: string
  trustedHint?: boolean
  secretHint?: boolean // NEW: Indicates tool output may include sensitive data
}

Default: secretHint = false.

When true, MCP clients should treat the tool’s output as potentially sensitive, applying extra safeguards (e.g., redaction, restricted logging, or user confirmation before exposing data).

Rationale

By making sensitivity explicit at the protocol level:

MCP clients can enforce consistent handling of sensitive data.

Developers gain a clear way to flag tools that may expose secrets.

Security risks from accidental leaks (e.g., via logs or UI rendering) are reduced.

This complements existing hints like trustedHint (which marks tools as safe to call), but addresses a different axis: sensitivity of returned data, not trust in the tool itself.

Backwards Compatibility

This is a non-breaking change:

Tools that don’t declare secretHint continue to behave as before.

Clients that don’t yet support secretHint simply ignore it.

Implementation

MCP specification updates should:

Add secretHint to the ToolAnnotations interface.

Define the default (false) and semantics when set to true.

Provide examples where tool responses might include API keys, PII, or other sensitive content.

Discussion

This SEP extends the expressiveness of MCP annotations. While hints remain advisory rather than guarantees, the addition of secretHint provides an explicit, protocol-level signal for sensitivity. This allows implementers to build stronger security postures and avoid accidental exposure of secrets.