Annotation Interface McpHeader

@Target({PARAMETER,RECORD_COMPONENT}) @Retention(RUNTIME) public @interface McpHeader
Publishes and enforces an MCP custom mirrored header for one typed tool input property.

The annotation name is the suffix of the corresponding Mcp-Param-* request header. For example, @McpHeader(name = "Region") publishes x-mcp-header: "Region" on the derived property schema and requires Mcp-Param-Region to agree with that property's request-body value whenever the value is present and non-null. If the body property is absent or null, the corresponding request header must also be absent; a mirrored header never supplies or injects a tool argument.

A method-parameter declaration must also carry McpToolArgument and belong to an McpTool method. A record-component declaration applies when that component is reached from a typed tool input solely through record properties; it may also carry McpToolProperty to customize its published property metadata. Mirrored properties must derive to the JSON Schema type string, boolean, or integer. Soklet rejects unsupported placements, other property types, invalid HTTP field-name suffixes, and case-insensitive name collisions while deriving the tool schema.

Integer safety is enforced on each request value. Types such as long, Long, and BigInteger are accepted without narrowing their derived schemas. Each mirrored integer value must be between -9007199254740991 and 9007199254740991, inclusive. Its header must use canonical decimal spelling: 0, or digits without leading zeros, optionally preceded by -; +1, 01, and -0 are invalid. A mathematically integral JSON number such as 1.0 or 1e0 can match the header 1. A mismatch produces the fixed HTTP 400 / JSON-RPC -32020 "Header mismatch" response after admission and before handler entry.

Mirrored headers require MCP 2026-07-28. Endpoint construction rejects a tool with mirrored-header declarations that selects either supported 2025 revision.

Mirrored headers can expose argument values to HTTP infrastructure. Do not mirror credentials, secrets, or other sensitive values unless that exposure is explicitly intended and protected by the deployment.

Author:
Mark Allen

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    @NonNull String
    name
    The non-empty HTTP field-name token appended to Mcp-Param-.

  • Element Details

    • name

      @NonNull String name
      The non-empty HTTP field-name token appended to Mcp-Param-.
      Returns:
      mirrored-header suffix