MCP Tool Annotations: The Four Hints and Their Defaults
MCP tool annotations are the readOnlyHint, destructiveHint, idempotentHint and openWorldHint fields a server attaches to a tool, and how clients use them.
6 min read
MCP logging lets a server send log messages to its client. The 2026-07-28 MCP spec deprecated it in favor of stderr logging and OpenTelemetry.
Model Context Protocol (MCP) servers passed one billion total downloads each for the TypeScript and Python SDKs by late 2026, with the Tier 1 SDKs adding close to half a billion downloads a month, according to the MCP blog's 28 July 2026 release post. That post announced the 2026-07-28 specification revision, and it deprecated one of the protocol's original features: MCP logging.
MCP logging is the part of the protocol that lets a server send structured log messages to the client running it, using syslog-style severity levels from debug to emergency. The 2026-07-28 spec revision deprecated the feature under SEP-2577, alongside Roots and Sampling, and tells implementers to log to stderr for stdio transports and use OpenTelemetry for observability instead.
A server that wants to use MCP logging declares a logging capability during setup:
{
"capabilities": {
"logging": {}
}
}It then sends notifications/message messages carrying a severity level, an optional logger name, and any JSON-serializable data. The eight levels follow RFC 5424's syslog scale, debug, info, notice, warning, error, critical, alert, and emergency, according to the protocol specification.
How a client controls which levels it receives changed with the 2026-07-28 revision. Before that date, a client sent a session-wide logging/setLevel request and the server held that minimum level for the rest of the connection. The 2026-07-28 spec drops protocol-level sessions entirely, so a client instead sets io.modelcontextprotocol/logLevel in a single request's _meta field. The server may then send notifications/message at or above that level only on the response stream for that one request, never on a separate subscription stream.
The spec also puts security limits on what a log message may carry. It must not contain credentials, secrets, personal identifying information, or internal system details that could aid an attack, and a server should rate limit messages, validate every field, and watch for sensitive content slipping through.
The official Python SDK stopped documenting MCP logging. Its handler guide states that "the 2026-07-28 revision of the spec deprecates that capability and does not replace it, so these docs don't teach it," and points developers to Python's own logging module instead:
import logging
from mcp.server import MCPServer
logger = logging.getLogger(__name__)
mcp = MCPServer("Bookshop")
@mcp.tool()
def search_books(query: str) -> str:
"""Search the catalog by title or author."""
logger.info("Searching for %r", query)
return f"Found 3 books matching {query!r}."
The SDK's default handler writes to standard error, which matters for a stdio server because the host reads MCP messages from standard output. The docs warn against calling print() in a stdio server for that reason. Passing log_level="DEBUG" to MCPServer(...) raises the default from "INFO", and an unhandled exception in a tool or resource function is logged automatically.
Not every framework dropped the protocol feature. FastMCP, a popular third-party server framework built on top of the SDKs, still implements it as ctx.debug(), ctx.info(), ctx.warning(), and ctx.error() methods inside a tool, sending the message to the connected client rather than to a file. A server sets a minimum level with FastMCP(client_log_level="warning"), and FastMCP's docs note that on a pre-2026-07-28 connection a client could override that per session with logging/setLevel, while "the modern protocol has no session to hold that level, so a modern client filters in its own log handler instead." Messages sent this way are also mirrored into the server's own log at the DEBUG level.
The TypeScript SDK's server guide keeps logging in its example server too. simpleStreamableHttp.ts, the SDK's feature-rich reference implementation, lists logging alongside sessions, tasks, and elicitation, and the guide has its own log level filtering section.
The deprecated features registry states the migration path for logging in one line: log to stderr for stdio transports, and use OpenTelemetry for observability. The Python SDK already does the second half without being asked. Creating an MCPServer or a low-level Server traces every inbound message as an OpenTelemetry span, named after its method, carrying mcp.method.name and mcp.protocol.version, and a tools/call span adds OpenTelemetry's GenAI semantic convention attributes, gen_ai.operation.name set to "execute_tool" and gen_ai.tool.name set to the tool's name.
That tracing costs nothing until someone wants to see it. The SDK depends only on the lightweight opentelemetry-api package, so with no exporter installed the spans are created and discarded. Running uv add opentelemetry-sdk opentelemetry-exporter-otlp and configuring an exporter lights the existing spans up with no change to the server's own code. When both the client and server run the SDK, trace context propagates across the wire under SEP-414, so a server's spans nest inside the client's trace instead of starting their own. Pydantic Logfire is one hosted backend built on OpenTelemetry that the SDK docs name as a one-line setup. Developers comparing dedicated tracing and logging tools for their servers can browse AI Agents Listing's monitoring and observability category.
MCP logging still has a narrow, useful role: watching a server's own log lines while developing it, for example by running the server with the MCP Inspector. The Python SDK docs are direct about who the feature is for: "Logging is for you, the person operating the server. The model never sees it." If the model needs to see something, the docs add, return it from the tool instead of logging it.
For anything beyond local debugging, the spec's own guidance is to build on OpenTelemetry rather than the deprecated capability. A new MCP server shipped after 2026-07-28 has little reason to declare the logging capability at all, since it still works for at least twelve months but gains nothing a standard logger and a trace exporter don't already cover. Hosts such as Claude Code connect to many servers at once, and a server that floods them with log notifications adds client-side noise that the spec's own rate limiting language exists to curb.
The MCP blog published the 2026-07-28 specification on 28 July 2026, in a post by lead maintainers David Soria Parra and Den Delimarsky. Its headline change is a stateless protocol core: the initialize/initialized handshake and the Mcp-Session-Id header are retired, and every request now carries its own protocol version and client identity so it can land on any server instance behind a plain load balancer. Server-initiated calls such as elicitation, sampling, and the old roots/list are replaced by Multi Round-Trip Requests, which let a stateless server ask the client a question mid-call without holding a connection open. Streamable HTTP requests must now carry Mcp-Method and Mcp-Name headers so a gateway can route and meter without parsing the JSON body, and tools/list, prompts/list, resources/list, and resources/read responses now carry ttlMs and cacheScope fields for client-side caching.

Under SEP-2577, the same release deprecated three client and server features at once: Roots, Sampling, and Logging. Per the deprecated features registry, all three remain part of the specification and keep working, with an earliest removal date of the first revision released on or after 2027-07-28. All four Tier 1 SDKs, TypeScript, Python, Go, and C#, shipped support for 2026-07-28 the same day as the spec, with the Rust SDK following in beta.
notifications/message.ctx.debug(), ctx.info(), ctx.warning(), and ctx.error().MCP logging is the Model Context Protocol capability that lets a server send structured log messages, from debug through emergency severity, to the client it's connected to, using the notifications/message method defined in the spec's logging utility.
Yes. The 2026-07-28 MCP specification deprecated logging under SEP-2577, along with Roots and Sampling. It still works and remains in the spec, but new servers shouldn't adopt it, and it becomes eligible for removal no earlier than the first revision released on or after 2027-07-28.
The spec's deprecated features registry recommends logging to stderr for stdio transports and using OpenTelemetry for observability. The official Python SDK traces every request as an OpenTelemetry span automatically, with no code required until an exporter is installed.
Yes. FastMCP still implements the protocol's client-logging feature as ctx.debug(), ctx.info(), ctx.warning(), and ctx.error() inside a tool, separate from ordinary server-side logging to files or console, and lets a server set a minimum level with client_log_level.
No. The spec requires that log messages never contain credentials, secrets, personal identifying information, or internal system details that could aid an attack, and that servers rate limit and validate what they send.
Teams picking an MCP server to build on can compare options on AI Agents Listing's MCP servers hub.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.
MCP tool annotations are the readOnlyHint, destructiveHint, idempotentHint and openWorldHint fields a server attaches to a tool, and how clients use them.
6 min read
AI agent identity management explained: the registration, scoped-credential and delegation steps behind it, and how Okta, Microsoft, Google and MCP differ.
7 min read
A comparison of seven no-code AI agents platforms in 2026, covering pricing, integrations and best use case for n8n, Zapier, Lindy, Relevance AI, Voiceflow, Gumloop and Botpress.
10 min read