Skip to content

03-base-protocol-messages-and-schema-contracts.md

Latest commit

 

History

History
235 lines (186 loc) · 7.5 KB

03-base-protocol-messages-and-schema-contracts.md

File metadata and controls

235 lines (186 loc) · 7.5 KB
layout default
title Chapter 3: Base Protocol Messages and Schema Contracts
nav_order 3
parent MCP Specification Tutorial

Chapter 3: Base Protocol Messages and Schema Contracts

Welcome to Chapter 3: Base Protocol Messages and Schema Contracts. In this part of MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

This chapter covers the core message and schema rules that keep implementations interoperable.

Learning Goals

  • distinguish requests, responses, and notifications correctly
  • apply JSON-RPC and MCP field constraints with fewer wire bugs
  • use JSON Schema dialect rules consistently
  • handle _meta and rich metadata fields predictably

Wire-Contract Rules That Matter

Area Practical Rule
JSON encoding UTF-8 encoded JSON-RPC messages only
Message framing transport-specific framing must preserve one valid JSON-RPC message per unit
Requests vs notifications requests expect response; notifications do not
Schema defaults JSON Schema 2020-12 is the default dialect in current revisions
Validation validate input and output schemas at boundaries, not deep inside tool logic

Implementation Guidance

  • maintain strict schema validation for tool/resource payloads
  • treat protocol errors separately from tool execution errors
  • enforce method-level payload shape expectations in a shared layer
  • pin schema artifacts by protocol revision when generating SDK bindings

Source References

Summary

You now have a protocol-contract baseline that reduces cross-client/server serialization and validation failures.

Next: Chapter 4: Transport Model: stdio, Streamable HTTP, and Sessions

Depth Expansion Playbook

Source Code Walkthrough

schema/2025-06-18/schema.ts

The Prompt interface in schema/2025-06-18/schema.ts handles a key part of this chapter's functionality:

}

/* Prompts */
/**
 * Sent from the client to request a list of prompts and prompt templates the server has.
 *
 * @category `prompts/list`
 */
export interface ListPromptsRequest extends PaginatedRequest {
  method: "prompts/list";
}

/**
 * The server's response to a prompts/list request from the client.
 *
 * @category `prompts/list`
 */
export interface ListPromptsResult extends PaginatedResult {
  prompts: Prompt[];
}

/**
 * Used by the client to get a prompt provided by the server.
 *
 * @category `prompts/get`
 */
export interface GetPromptRequest extends Request {
  method: "prompts/get";
  params: {
    /**
     * The name of the prompt or prompt template.
     */

This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.

schema/2025-06-18/schema.ts

The PromptArgument interface in schema/2025-06-18/schema.ts handles a key part of this chapter's functionality:

   * A list of arguments to use for templating the prompt.
   */
  arguments?: PromptArgument[];

  /**
   * See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
   */
  _meta?: { [key: string]: unknown };
}

/**
 * Describes an argument that a prompt can accept.
 *
 * @category `prompts/list`
 */
export interface PromptArgument extends BaseMetadata {
  /**
   * A human-readable description of the argument.
   */
  description?: string;
  /**
   * Whether this argument must be provided.
   */
  required?: boolean;
}

/**
 * The sender or recipient of messages and data in a conversation.
 *
 * @category Common Types
 */
export type Role = "user" | "assistant";

This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.

schema/2025-06-18/schema.ts

The PromptMessage interface in schema/2025-06-18/schema.ts handles a key part of this chapter's functionality:

   */
  description?: string;
  messages: PromptMessage[];
}

/**
 * A prompt or prompt template that the server offers.
 *
 * @category `prompts/list`
 */
export interface Prompt extends BaseMetadata {
  /**
   * An optional description of what this prompt provides
   */
  description?: string;
  /**
   * A list of arguments to use for templating the prompt.
   */
  arguments?: PromptArgument[];

  /**
   * See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
   */
  _meta?: { [key: string]: unknown };
}

/**
 * Describes an argument that a prompt can accept.
 *
 * @category `prompts/list`
 */
export interface PromptArgument extends BaseMetadata {

This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.

schema/2025-06-18/schema.ts

The ResourceLink interface in schema/2025-06-18/schema.ts handles a key part of this chapter's functionality:

 * @category Content
 */
export interface ResourceLink extends Resource {
  type: "resource_link";
}

/**
 * The contents of a resource, embedded into a prompt or tool call result.
 *
 * It is up to the client how best to render embedded resources for the benefit
 * of the LLM and/or the user.
 *
 * @category Content
 */
export interface EmbeddedResource {
  type: "resource";
  resource: TextResourceContents | BlobResourceContents;

  /**
   * Optional annotations for the client.
   */
  annotations?: Annotations;

  /**
   * See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
   */
  _meta?: { [key: string]: unknown };
}
/**
 * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.
 *
 * @category `notifications/prompts/list_changed`

This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.

How These Components Connect

flowchart TD
    A[Prompt]
    B[PromptArgument]
    C[PromptMessage]
    D[ResourceLink]
    E[EmbeddedResource]
    A --> B
    B --> C
    C --> D
    D --> E
Loading