Preamble

Add Data Models directly into MCP Spec

Authors: Jonathan Hefner (@jonathanhefner, Kurtis Van Gent(@kurtisvg) (on behalf of the Transport Working Group)

Abstract

This SEP proposes a new standard for structuring Model Context Protocol specification documents. The core of this proposal is to represent all information related to a specific protocol feature—its data model, associated protocol methods, and illustrative examples—in a single, unified location. By co-locating these related pieces of information, we aim to enhance clarity, reduce ambiguity, and improve the overall developer experience for those implementing or using the protocol.

Motivation

Currently, information within our specification documents can be fragmented. A developer might need to consult one section for a data model definition, another for the protocol methods that operate on that model, and yet another for usage examples. This separation creates several challenges:

• Increased Cognitive Load: Developers must build a mental model by piecing together information from disparate sections, increasing the effort required to understand a feature completely.
• Risk of Inconsistency: When related information is scattered, it is easier for it to become desynchronized. A change to a data model might not be reflected in all relevant examples or method descriptions, leading to confusion and implementation errors.
• Maintenance Overhead: Updating a single logical feature requires editing multiple locations within the documentation, making the maintenance process more complex and error-prone.
• Poor Discoverability: It can be difficult for newcomers to find all the necessary information related to the specific part of the protocol they are trying to implement.

By creating a "single source of truth" for each component of the spec, where all related parts are presented together, we can create a more coherent, consistent, and maintainable set of documentation.

Specification

Here is a before-and-after example of how the tools/call method would be represented

Before

### Calling Tools

To invoke a tool, clients send a `tools/call` request:

**Request:**

``json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    }
  }
}
``

**Response:**

``json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false
  }
}
``

After

With the proposed changes, the specification would more clearly represent the schema, method, and example together on the page:

### tools/call

A request to invoke a tool:

*   Request params type: ToolCallParams
*   Response result type (on success): ToolCallResult
*   Response error type (on failure): JSONRPCError

``ts
export interface CallToolRequest extends Request {
  method: "tools/call";
  params: CallToolParams;
}
``

#### ToolCallParams object

``ts
/**
 * Used by the client to invoke a tool provided by the server.
 */
export interface CallToolParams {
    name: string;
    arguments?: { [key: string]: any };
}
``

#### ToolCallResult object

``ts
export interface ToolCallResult extends Result {
  /**
   * A list of content objects that represent the unstructured result of the tool call.
   */
  content: ContentBlock[];

  /**
   * An optional JSON object that represents the structured result of the tool call.
   */
  structuredContent?: { [key: string]: unknown };

  /**
   * Whether the tool call ended in an error.
   *
   * If not set, this is assumed to be false (the call was successful).
   *
   * Any errors that originate from the tool SHOULD be reported inside the result
   * object, with `isError` set to true, _not_ as an MCP protocol-level error
   * response. Otherwise, the LLM would not be able to see that an error occurred
   * and self-correct.
   *
   * However, any errors in _finding_ the tool, an error indicating that the
   * server does not support tool calls, or any other exceptional conditions,
   * should be reported as an MCP error response.
   */
  isError?: boolean;
}
``

#### **Example request:**

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "toolName": "calculator",
    "inputs": {
      "expression": "2 + 2"
    }
  },
  "id": 1

Backards Compatibility

This change is mostly a visual representation, and might be possible without backwards compatible changes. If breaking changes are required in the schema.ts to support this change, they can be introduced in the next published version of the protocol instead and shouldn't affect backwards compatibility between versions.

Reference Implementation

Coming soon.

Security Implications

N/A.