modelcontextprotocol · jpmcb · Jun 30, 2025
@@ -104,7 +104,7 @@ and instead retrieve credentials from the environment.
 Additionally, clients and servers **MAY** negotiate their own custom authentication and
 authorization strategies.
 
-For further discussions and contributions to the evolution of MCP’s auth mechanisms, join
+For further discussions and contributions to the evolution of MCP's auth mechanisms, join
 us in
 [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
 to help shape the future of the protocol!
@@ -120,9 +120,81 @@ There is also a
 which is automatically generated from the TypeScript source of truth, for use with
 various automated tooling.
 
-### General fields
+## JSON Schema Usage
 
-#### `_meta`
+The Model Context Protocol uses JSON Schema for validation throughout the protocol. This section clarifies how JSON Schema should be used within MCP messages.
+
+### Schema Dialect
+
+MCP supports JSON Schema with the following rules:
+
+1. **Default dialect**: When a schema does not include a `$schema` field, it defaults to JSON Schema 2020-12 (`https://json-schema.org/draft/2020-12/schema`)
+2. **Explicit dialect**: Schemas MAY include a `$schema` field to specify a different dialect
+3. **Supported dialects**: Implementations MUST support at least 2020-12 and SHOULD document which additional dialects they support
+4. **Recommendation**: Implementors are RECOMMENDED to use JSON Schema 2020-12.
+
+### Example Usage
+
+#### Default dialect (2020-12):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "age": { "type": "integer", "minimum": 0 }
+  },
+  "required": ["name"]
+}
+```
+
+#### Explicit dialect (draft-07):
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "age": { "type": "integer", "minimum": 0 }
+  },
+  "required": ["name"]
+}
+```
+
+### Implementation Requirements
+
+- Clients and servers **MUST** support JSON Schema 2020-12 for schemas without an explicit `$schema` field
+- Clients and servers **SHOULD** validate schemas according to their declared or default dialect
+- Clients and servers **SHOULD** document which schema dialects they support
+- Clients and servers **SHOULD** handle schemas with unsupported dialects gracefully by returning an appropriate error indicating the dialect is not supported
+
+### Schema Validation
+
+- Schemas **MUST** be valid according to their declared or default dialect
+- Schema properties **MUST NOT** contain `null` values as `null` is invalid in all JSON Schema versions
+- The `inputSchema` field **MUST NOT** be `null` - for tools with no parameters, use one of these valid approaches:
+  - `true` - accepts any input (most permissive)
+  - `{}` - equivalent to `true`, accepts any input
+  - `{ "additionalProperties": true }` - equivalent to `true`, accepts any input
+  - `{ "type": "object" }` - accepts any object
+  - `{ "type": "object", "additionalProperties": false }` - accepts only an empty objects
+
+  Example for a tool with no parameters:
+
+  ```json
+  {
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "This tool requires no parameters"
+    }
+  }
+  ```
+
+## General fields
+
+### `_meta`
 
 The `_meta` property/parameter is reserved by MCP to allow clients and servers
 to attach additional metadata to their interactions.

@@ -198,7 +198,9 @@ sequenceDiagram
 
 ## Request Schema
 
-The `requestedSchema` field allows servers to define the structure of the expected response using a restricted subset of JSON Schema. To simplify client user experience, elicitation schemas are limited to flat objects with primitive properties only:
+The `requestedSchema` field allows servers to define the structure of the expected response using a restricted subset of JSON Schema. To simplify implementation for clients, elicitation schemas are limited to flat objects with primitive properties only.
+
+Elicitation schemas follow the [JSON Schema usage guidelines](/specification/draft/basic#json-schema-usage) with additional restrictions:
 
 ```json
 "requestedSchema": {

@@ -194,14 +194,16 @@ A tool definition includes:
 - `title`: Optional human-readable name of the tool for display purposes.
 - `description`: Human-readable description of functionality
 - `inputSchema`: JSON Schema defining expected parameters
+  - Follows the [JSON Schema usage guidelines](/specification/draft/basic#json-schema-usage)
+  - Defaults to 2020-12 if no `$schema` field is present
 - `outputSchema`: Optional JSON Schema defining expected output structure
+  - Follows the [JSON Schema usage guidelines](/specification/draft/basic#json-schema-usage)
+  - Defaults to 2020-12 if no `$schema` field is present
 - `annotations`: optional properties describing tool behavior
 
 <Warning>
-
-For trust & safety and security, clients **MUST** consider
-tool annotations to be untrusted unless they come from trusted servers.
-
+  For trust & safety and security, clients **MUST** consider tool annotations to
+  be untrusted unless they come from trusted servers.
 </Warning>
 
 ### Tool Result
@@ -298,13 +300,13 @@ Embedded resources support the same [Resource annotations](/specification/draft/
 
 #### Structured Content
 
-**Structured** content is returned as a JSON object in the `structuredContent` field of a result.
+**Structured** content is returned as a JSON value in the `structuredContent` field of a result. This can be any valid JSON: objects, arrays, strings, numbers, booleans, or null.
 
 For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block.
 
 #### Output Schema
 
-Tools may also provide an output schema for validation of structured results.
+Tools may also provide an output schema for validation of structured results. The output schema can be any valid [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12), supporting all JSON types and schema composition features.
 If an output schema is provided:
 
 - Servers **MUST** provide structured results that conform to this schema.
@@ -377,6 +379,49 @@ Providing an output schema helps clients and LLMs understand and properly handle
 - Guiding clients and LLMs to properly parse and utilize the returned data
 - Supporting better documentation and developer experience
 
+### Schema Examples
+
+#### Tool with default 2020-12 schema:
+
+```json
+{
+  "name": "calculate_sum",
+  "description": "Add two numbers",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "a": { "type": "number" },
+      "b": { "type": "number" }
+    },
+    "required": ["a", "b"]
+  }
+}
+```
+
+#### Tool with explicit draft-07 schema:
+
+```json
+{
+  "name": "search_products",
+  "description": "Search for products with filters",
+  "inputSchema": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "properties": {
+      "query": { "type": "string" },
+      "filters": {
+        "type": "object",
+        "properties": {
+          "minPrice": { "type": "number", "minimum": 0 },
+          "maxPrice": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "required": ["query"]
+  }
+}
+```
+
 ## Error Handling
 
 Tools use two error reporting mechanisms:

@@ -845,9 +845,10 @@ export interface CallToolResult extends Result {
   content: ContentBlock[];
 
   /**
-   * An optional JSON object that represents the structured result of the tool call.
+   * An optional JSON value that represents the structured result of the tool call.
+   * MUST conform to the outputSchema if specified in the tool definition.
    */
-  structuredContent?: { [key: string]: unknown };
+  structuredContent?: unknown;
 
   /**
    * Whether the tool call ended in an error.
@@ -955,21 +956,22 @@ export interface Tool extends BaseMetadata, Icons {
 
   /**
    * A JSON Schema object defining the expected parameters for the tool.
+   * While tools receive arguments as objects, this can be any valid JSON Schema to allow for
+   * sophisticated object validation patterns (like with "oneOf", "anyOf", etc.)
    */
   inputSchema: {
+    $schema?: string;
     type: "object";
-    properties?: { [key: string]: object };
-    required?: string[];
+    [key: string]: any;
   };
 
   /**
    * An optional JSON Schema object defining the structure of the tool's output returned in
-   * the structuredContent field of a CallToolResult.
+   * the structuredContent field of a CallToolResult. This can be any valid JSON 2020-12 Schema.
    */
   outputSchema?: {
-    type: "object";
-    properties?: { [key: string]: object };
-    required?: string[];
+    $schema?: string;
+    [key: string]: any;
   };
 
   /**
@@ -1464,11 +1466,8 @@ export interface ElicitRequest extends JSONRPCRequest {
      * Only top-level properties are allowed, without nesting.
      */
     requestedSchema: {
-      type: "object";
-      properties: {
-        [key: string]: PrimitiveSchemaDefinition;
-      };
-      required?: string[];
+      $schema?: string;
+      [key: string]: any;
     };
   };
 }