MCP PHP SDK

McpHeader

FinalYes

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
see
https://modelcontextprotocol.io/specification/2026-07-28/basic/transports#http-headers
author

Christopher Hertel mail@christopher-hertel.de

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 = '?='
SCHEMA_KEYWORDS  : mixed = ['items', 'prefixItems', 'additionalItems', 'ad...
Keywords whose value is a subschema or a list of subschemas.
SCHEMA_MAP_KEYWORDS  : mixed = ['properties', 'patternProperties', '$defs', 'd...
Keywords whose values map arbitrary names to subschemas.

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.
lookup()  : string|null
Case-insensitive header lookup, since PSR-7 preserves the sender's casing.
nameFor()  : string|null
The subject of a request, per method. Anything unlisted is exempt.
findUnreachable()  : string|null
The path of the first annotation that does not sit on a property reached through a chain of `properties`, e.g. one under `items`, `anyOf` or `$defs`.
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

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 = '?='

SCHEMA_KEYWORDS

Keywords whose value is a subschema or a list of subschemas.

private mixed SCHEMA_KEYWORDS = ['items', 'prefixItems', 'additionalItems', 'additionalProperties', 'allOf', 'anyOf', 'oneOf', 'not', 'if', 'then', 'else', 'contains', 'propertyNames', 'unevaluatedItems', 'unevaluatedProperties', 'contentSchema']

SCHEMA_MAP_KEYWORDS

Keywords whose values map arbitrary names to subschemas.

private mixed SCHEMA_MAP_KEYWORDS = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas', 'dependencies']

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|null

encode()

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|null

lookup()

Case-insensitive header lookup, since PSR-7 preserves the sender's casing.

public static lookup(array<string, string> $headers, string $name) : string|null
Parameters
$headers : array<string, string>
$name : string
Return values
string|null

nameFor()

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|null

findUnreachable()

The path of the first annotation that does not sit on a property reached through a chain of `properties`, e.g. one under `items`, `anyOf` or `$defs`.

private static findUnreachable(array<string|int, mixed> $schema, string $path, bool $reachable) : string|null
Parameters
$schema : array<string|int, mixed>
$path : string
$reachable : bool
Return values
string|null

isSafe()

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
bool

wrap()

private static wrap(string $value) : string
Parameters
$value : string
Return values
string
On this page

Search results