MCP 2026-07-28
ModelContextProtocol.jl supports both the stateful MCP 2025-11-25 protocol and the stateless MCP 2026-07-28 protocol over Streamable HTTP. The client defaults to 2025-11-25 for compatibility. The server accepts both versions with its default configuration.
Legacy clients can omit the MCP-Protocol-Version HTTP header on their first initialize request, which negotiates the version in params.protocolVersion. Later legacy requests still follow the server's missing-header policy. Modern requests always require matching version metadata and HTTP headers. Handlers receive the request's protocol version even when the server prefers the other era, so modern capability checks and input_required results remain limited to modern requests. Supported legacy clients can also open their event stream and terminate their session regardless of the server's preferred version. These standalone GET and DELETE operations return HTTP 405 for an advertised modern version and HTTP 400 for unsupported versions.
Select the stateless client
Set the version when you prepare the client. initialize_client! then calls server/discover. It does not send the removed initialize method.
using ModelContextProtocol
discovery = discover_server("https://mcp.example.com")
client = prepare_manual_client(
discovery;
config=MCPClientConfig(
protocol_version=ModelContextProtocol.PROTOCOL_VERSION_2026_07_28,
),
capabilities=Dict("elicitation" => Dict()),
)
server_info = initialize_client!(client)Each request includes the required protocol version, client capabilities, and client identity in params._meta. Streamable HTTP requests also include the required Mcp-Method and Mcp-Name headers. The package rejects a response or request that violates the matching rules.
The ordinary HTTP request helpers retry once when a matching UnsupportedProtocolVersionError (-32022, HTTP 400) advertises 2026-07-28. The retry updates the version header and metadata together while preserving the request ID, arguments, other metadata, and headers. It applies only to that request; the client's configured version stays unchanged. Invalid or unrelated errors, repeated rejections, and servers offering no compatible modern version remain errors. This does not add automatic fallback to a legacy session or version retry for stdio and long-lived subscription listeners.
This follows the dated specifications for legacy version headers and modern version negotiation.
The modern protocol does not use sessions, notifications/initialized, notifications/cancelled over HTTP, ping, logging/setLevel, or the old resource subscription methods. The client reports an error if an application tries to use one of these legacy calls in modern mode. terminate_session! only clears local client state in modern mode.
Require a client capability
A tool can state the client capability that it needs for modern requests. The server checks the capability before it invokes the handler in that protocol.
using ModelContextProtocol
server = MCPServer(name="Approval server", version="0.1.0")
register_tool!(
server;
name="approve",
required_client_capabilities=Dict("elicitation" => Dict()),
handler=(_context, _arguments) -> Dict(
"content" => [Dict("type" => "text", "text" => "approved")],
),
)
server.tools["approve"].required_client_capabilitiesDict{String, Any} with 1 entry:
"elicitation" => Dict{String, Any}()If the request omits a required capability, the server returns MissingRequiredClientCapability (-32021) with HTTP status 400. Nested capability requirements are checked recursively.
For MCPInputRequired, the package removes input requests for capabilities that the client did not declare. It returns MissingRequiredClientCapability only when no requested interaction is supported.
Multi-round-trip requests
A handler returns MCPInputRequired when it needs sampling, roots, elicitation, or another client operation before it can finish.
register_tool!(
server;
name="confirm-delete",
handler=function (context, _arguments)
responses = ModelContextProtocol.input_responses(context)
if responses === nothing
return MCPInputRequired(
input_requests=Dict(
"approval" => Dict(
"method" => "elicitation/create",
"params" => Dict(
"message" => "Delete the record?",
"requestedSchema" => Dict(
"type" => "object",
"properties" => Dict(
"confirmed" => Dict("type" => "boolean"),
),
"required" => ["confirmed"],
),
),
),
),
request_state="delete-record-42",
)
end
return Dict(
"content" => [Dict("type" => "text", "text" => "deleted")],
)
end,
)The client receives a result with resultType == "input_required". It sends the next attempt with input_responses and the returned request_state:
retry = call_tool(
client,
"confirm-delete";
input_responses=Dict("approval" => Dict("action" => "accept")),
request_state="delete-record-42",
)The application owns the approval or sampling interaction. The package does not perform it automatically.
Custom tool headers
Use x-mcp-header on a tool input property when an HTTP intermediary must see that value without parsing JSON.
header_schema = Dict(
"type" => "object",
"properties" => Dict(
"region" => Dict(
"type" => "string",
"x-mcp-header" => "Region",
),
),
)
register_tool!(
server;
name="route-query",
input_schema=header_schema,
handler=(_context, _arguments) -> Dict(
"content" => [Dict("type" => "text", "text" => "ok")],
),
)
server.tools["route-query"].input_schema["properties"]["region"]["x-mcp-header"]"Region"The modern client reads the schema from tools/list. It sends a matching Mcp-Param-Region header on tools/call. It encodes unsafe text as UTF-8 Base64. It excludes malformed tool definitions from tools/list. The server validates recognized custom headers before it invokes the tool.
For a known tool, the client serializes supplied arguments once and uses that same JSON object for header values and the request body. Custom JSON lowering therefore cannot produce different values for routing and tool execution. Arguments must be a dictionary or named tuple that lowers to a JSON object. Omitting arguments keeps the field absent from the request.
Only string, integer, and boolean properties can use this annotation. Integers must be in the JavaScript safe-integer range. Header names must be unique HTTP field-name tokens. Do not expose passwords, tokens, or personal data in these headers.
Subscriptions and request events
Use the namespaced subscription API for modern list-change and resource notifications:
listen = ModelContextProtocol.listen_subscriptions!(
client;
tools_list_changed=true,
resource_uris=["memory://report"],
)Register handlers with register_notification_handler! before you start the listener. A server can end all active streams with ModelContextProtocol.close_subscription_listeners! during shutdown.
Tool handlers can call ModelContextProtocol.send_progress! and ModelContextProtocol.send_log!. The current server preserves event order but buffers request-scoped events until the handler returns. Use subscriptions/listen when an event must arrive independently of one request.
Cache metadata
Modern discovery and list results include ttlMs and cacheScope. Configure them with cache_ttl_ms and cache_scope in MCPServerConfig. The time must not be negative. The scope must be "private" or "public".
Conformance adapter
The repository includes test/conformance_client.jl. It lets the official MCP conformance runner exercise this package as a client. The normal Julia test suite contains permanent regression checks for the same wire contracts.