MCP messages: discovery, calls, and results

Your MCP server starts successfully, yet the assistant says it cannot use the tool. Which message would you inspect first? Knowing the protocol's shape helps you find the fault without changing prompts at random.

Before you begin: Complete the MCP connection and server lessons. Know the shape of a JSON object.

Begin with the connection lifecycle

MCP uses JSON-RPC messages and a defined initialization exchange. Participants negotiate a protocol version and advertise capabilities before normal interaction. An SDK handles much of the message machinery. Understanding it still matters when a host and server disagree about supported features.

The protocol revision and package version answer different questions. The revision describes the agreed message contract. The SDK version identifies the implementation you installed. September 10, 2026's review used the July 28, 2026 specification and the Python SDK's v2 documentation.

Inspect discovery before execution

Tools expose callable operations. Resources expose readable content identified by URIs. Prompts expose reusable prompt templates. These are protocol concepts, not guarantees that every host presents all three in the same interface.

For a tool, discovery includes its name, description, and input schema. The host needs enough information to construct a valid call. If a tool is missing from discovery, investigate server registration, advertised capabilities, and host connection state before investigating the model's selection behavior.

The simplified request below illustrates a tools/call message after initialization. It is a protocol example, not a complete client program or a recorded network trace.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "read_workshop",
    "arguments": {"workshop_id": "W1"}
  }
}

The request ID correlates a response with this request. It is not an authenticated user ID, a database key, or an idempotency guarantee for a write. Those identities may all exist in an application, but they serve different purposes.

Read success at the right layer

A successful HTTP response can contain a protocol-level result that reports a tool failure. A successful tool invocation can return a legitimate not_found business result. A successful lookup can still be paraphrased incorrectly by the model.

For example, malformed request arguments belong to validation or protocol handling. “Catalog service unavailable” is a tool execution problem. “W99 does not exist” can be a normal domain result. Preserve these distinctions so the host can offer an appropriate next step.

Tool results may carry textual content and structured content according to the supported specification and schema. Read the tool's documented output contract rather than assuming every server returns a plain string. If the contract says capacity is unknown, preserve that state instead of converting it to zero.

Trace one ambiguous failure

The transport returns HTTP 200, the tool result indicates a backend timeout, and the assistant answers “No matching workshops.” Which layer first lost meaning?

For practice, create three expected traces: missing tool, invalid argument, and valid request for an absent record. Write the recovery message for each. The missing tool may require connection repair; the invalid argument may require correction; the absent record may require a different question. Retrying all three identically wastes work and hides the cause.

Next, return to document applications and inspect the data transformations that happen behind an indexing abstraction.

Sources

MCP specification defines the lifecycle. Tools defines discovery, calls, and tool results. Architecture connects these messages to application roles.

Continue to the next lesson.