McpHeader
The HTTP header vocabulary that mirrors a request's JSON-RPC body (SEP-2243).
Both sides of the wire need the same answers — which header carries a method's subject, and how a value that is not header-safe is wrapped — so the rules live here rather than once in the client's emitter and again in the server's validator, where they could quietly disagree.
Tags
Table of Contents
Constants
- METHOD : mixed = 'Mcp-Method'
- NAME : mixed = 'Mcp-Name'
- PARAM_PREFIX : mixed = 'Mcp-Param-'
- PROTOCOL_VERSION : mixed = 'MCP-Protocol-Version'
- BASE64_PREFIX : mixed = '=?base64?'
- Wrapper marking a header value as Base64 of its UTF-8 representation.
- BASE64_SUFFIX : mixed = '?='
Methods
- annotations() : array<int, array{string, ?string, string}>
- Every annotation reachable through `properties` alone, as name, declared type and dotted path.
- checkAnnotations() : string|null
- Validates every `x-mcp-header` annotation reachable through `properties` in an input schema (SEP-2243).
- decode() : string|null
- Unwraps a `=?base64?…?=` value, or returns a plain value unchanged.
- encode() : string|null
- Renders a mirrored argument as a header value, wrapping it when it is not header-safe.
- nameFor() : string|null
- The subject of a request, per method. Anything unlisted is exempt.
- isSafe() : bool
- Printable US-ASCII with no leading or trailing whitespace. Interior spaces are fine; a tab is not, since it is a control character that field parsers are allowed to fold.
- wrap() : string
Constants
METHOD
public
mixed
METHOD
= 'Mcp-Method'
NAME
public
mixed
NAME
= 'Mcp-Name'
PARAM_PREFIX
public
mixed
PARAM_PREFIX
= 'Mcp-Param-'
PROTOCOL_VERSION
public
mixed
PROTOCOL_VERSION
= 'MCP-Protocol-Version'
BASE64_PREFIX
Wrapper marking a header value as Base64 of its UTF-8 representation.
private
mixed
BASE64_PREFIX
= '=?base64?'
BASE64_SUFFIX
private
mixed
BASE64_SUFFIX
= '?='
Methods
annotations()
Every annotation reachable through `properties` alone, as name, declared type and dotted path.
public
static annotations(array<string, mixed> $schema[, string $prefix = '' ]) : array<int, array{string, ?string, string}>
Parameters
- $schema : array<string, mixed>
- $prefix : string = ''
Return values
array<int, array{string, ?string, string}>checkAnnotations()
Validates every `x-mcp-header` annotation reachable through `properties` in an input schema (SEP-2243).
public
static checkAnnotations(array<string, mixed> $schema) : string|null
The value becomes an HTTP field name, so it has to be one; it has to be
unique case-insensitively, or two arguments would fight over one header;
and it may only sit on a primitive that is not number, because a float
has no single decimal spelling for a receiver to compare against.
Parameters
- $schema : array<string, mixed>
Return values
string|null —the reason it is invalid, or null when every annotation is well-formed
decode()
Unwraps a `=?base64?…?=` value, or returns a plain value unchanged.
public
static decode(string $value) : string|null
Strict: PHP's decoder accepts mispadded input and returns plausible bytes, which would turn a corrupted header into a silent mismatch. Null when the wrapper is present but its contents are not valid Base64.
Parameters
- $value : string
Return values
string|nullencode()
Renders a mirrored argument as a header value, wrapping it when it is not header-safe.
public
static encode(mixed $value) : string|null
Booleans travel as true/false and integers as decimal digits, both of
which are always safe. A string is wrapped when it carries a control
character, anything outside US-ASCII, or leading or trailing whitespace —
the last because a receiver is entitled to trim the value (RFC 9110
§5.5), which would otherwise silently change it.
Returns null for a value that cannot be mirrored at all.
Parameters
- $value : mixed
Return values
string|nullnameFor()
The subject of a request, per method. Anything unlisted is exempt.
public
static nameFor(string $method, array<string, mixed>|null $params) : string|null
Parameters
- $method : string
- $params : array<string, mixed>|null
Return values
string|nullisSafe()
Printable US-ASCII with no leading or trailing whitespace. Interior spaces are fine; a tab is not, since it is a control character that field parsers are allowed to fold.
private
static isSafe(string $value) : bool
A literal that already has the wrapper's shape is not safe either: sent unchanged, self::decode() would unwrap it as if it were Base64 and hand back something other than the literal.
Parameters
- $value : string
Return values
boolwrap()
private
static wrap(string $value) : string
Parameters
- $value : string