MCP primitives: tools, resources and prompts

An MCP server can offer three kinds of things. They differ less in what they contain than in who decides to use them. That question is the fastest way to choose the right one.

Tools: the model decides

Tools are functions the model calls when it thinks they help, for example kubectl_get_pods or pagerduty_ack_incident. Clients discover them with tools/list and run them with tools/call. A tool definition has a name, a description, an inputSchema and, optionally, a title, an outputSchema and annotations.

A tool result carries content, a list of text, image, audio, resource_link or embedded resource items. It can also include structuredContent: JSON that matches the outputSchema, if the tool declares one. isError: true marks a failed run (lesson 2).

Annotations are hints about behaviour:

The defaults are pessimistic on purpose. A tool that says nothing is treated as possibly destructive. Claude Code uses readOnlyHint and idempotentHint, for example to run read-only calls in parallel and to retry a safe call after a dropped connection.

Resources: the application decides

Resources are data identified by a URI, such as file:///etc/app.yaml, runbook://payments or postgres://schema/users. The host application decides when to load them and how much to show the model. Usually that happens because the user attached them. Clients use:

• resources/list for fixed resources.
• resources/templates/list for parameterised URIs, such as runbook://{service}.
• resources/read to fetch the content.
• subscriptions/listen to get change notifications. In 2026-07-28 this replaces the older resources/subscribe.

In Claude Code you attach a resource with an @ mention: @k8s-ro:runbook://payments.

Prompts: the user decides

Prompts are templates the user picks on purpose, usually from a slash menu. prompts/list shows them with their arguments, and prompts/get renders one into messages. Prompt arguments are simple named string values, not a JSON Schema. In Claude Code an MCP prompt appears as a command: /mcp__k8s-ro__triage payments.

# add to server.py from lesson 4
from pathlib import Path

RUNBOOKS = Path(__file__).parent / "runbooks"  # e.g. runbooks/payments.md

@mcp.resource("runbook://{service}")
def runbook(service: str) -> str:
    """On-call runbook for one service: owners, dashboards, known failure modes."""
    path = RUNBOOKS / f"{service}.md"
    if not path.is_file() or path.resolve().parent != RUNBOOKS.resolve():
        raise ValueError(f"No runbook for {service!r}")
    return path.read_text()

@mcp.prompt()
def triage(service: str) -> str:
    """Start a read-only triage of one service."""
    return (f"Triage {service}. First call kubectl_get_pods for its namespace, list pods that are "
            f"not Ready or have restarts, then read runbook://{service} and suggest next steps. "
            "Do not propose any change that writes to the cluster.")

Which primitive?

A single server often offers all three. A database server might expose a query tool, a schema resource and a “write a safe migration” prompt.

Client features

Servers can also ask things of the client. In 2026-07-28 the active feature is elicitation (elicitation/create), which lets a server ask the user for input or confirmation. It is now carried in the result as an “input required” response, using the multi round-trip request pattern, rather than sent as a separate server-to-client request.

Sampling, roots and logging are deprecated as of 2026-07-28. They still work during the deprecation window, but new servers shouldn’t use them:

• Instead of sampling, call an LLM API directly.
• Instead of roots, pass paths as tool arguments or server configuration.
• Instead of logging, write to stderr, or use OpenTelemetry.

Recap

• Tools are model-controlled, resources are application-controlled (URIs and templates), and prompts are user-controlled (slash commands).
• Tool results have content, optional structuredContent that matches outputSchema, and isError.
• Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are hints with cautious defaults. Never trust them from an untrusted server.
• In Claude Code, use @server:uri for resources and /mcp__server__prompt for prompts.
• Elicitation is current. Sampling, roots and logging are deprecated in 2026-07-28.