Schema Reference

Complete reference for input schemas and response formats in MCP tools

Schema Overview

MCP tools use JSON Schema to define input validation and help AI understand what data your tools expect. Well-defined schemas improve tool reliability and user experience.

Schema Benefits

Input Validation: Catch errors before tool execution
AI Understanding: Help AI provide the right data
Auto-completion: Enable smart IDE features
Documentation: Self-documenting parameter requirements

Basic Data Types

String

Text data with optional format validation and constraints.

{
 "type": "string",
 "description": "User's email address",
 "format": "email", // email, uri, date, time, uuid
 "minLength": 5,
 "maxLength": 100,
 "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
}

Common String Formats:

email: user@example.com
uri: https://example.com/path
date: 2024-01-15 (YYYY-MM-DD)
time: 14:30:00 (HH:MM:SS)
date-time: 2024-01-15T14:30:00Z
uuid: 123e4567-e89b-12d3-a456-426614174000

Number

Numeric data with range validation and precision control.

{
 "type": "number",
 "description": "Product price in USD",
 "minimum": 0,
 "maximum": 10000,
 "exclusiveMinimum": true, // > 0 instead of >= 0
 "multipleOf": 0.01 // Enforces 2 decimal places
}

// For integers specifically
{
 "type": "integer",
 "description": "Number of items",
 "minimum": 1,
 "maximum": 100
}

Boolean

True/false values for flags and options.

{
 "type": "boolean",
 "description": "Include archived items in results",
 "default": false
}

Enum (Fixed Options)

Restrict values to a specific set of options.

{
 "type": "string",
 "description": "Sort order for results",
 "enum": ["asc", "desc", "relevance"],
 "default": "relevance"
}

// Or with descriptions
{
 "type": "string",
 "description": "User role level",
 "enum": ["admin", "editor", "viewer"],
 "enumDescriptions": [
 "Full system access",
 "Can edit content",
 "Read-only access"
 ]
}

Complex Data Types

Object

Structured data with named properties.

{
 "type": "object",
 "description": "User profile information",
 "properties": {
 "name": {
 "type": "string",
 "description": "Full name"
 },
 "age": {
 "type": "integer",
 "minimum": 0,
 "maximum": 150
 },
 "email": {
 "type": "string",
 "format": "email"
 },
 "preferences": {
 "type": "object",
 "properties": {
 "theme": {
 "type": "string",
 "enum": ["light", "dark"]
 },
 "notifications": {
 "type": "boolean",
 "default": true
 }
 }
 }
 },
 "required": ["name", "email"],
 "additionalProperties": false // Reject unknown properties
}

Array

Lists of items with type validation and size constraints.

// Array of strings
{
 "type": "array",
 "description": "List of categories to filter by",
 "items": {
 "type": "string",
 "enum": ["tech", "business", "health", "sports"]
 },
 "minItems": 1,
 "maxItems": 5,
 "uniqueItems": true
}

// Array of objects
{
 "type": "array",
 "description": "List of products to process",
 "items": {
 "type": "object",
 "properties": {
 "id": { "type": "string" },
 "quantity": { "type": "integer", "minimum": 1 }
 },
 "required": ["id", "quantity"]
 },
 "minItems": 1,
 "maxItems": 100
}

Conditional Schemas

Advanced validation that depends on other field values.

If/Then/Else

Require different fields based on conditions.

{
 "type": "object",
 "properties": {
 "paymentMethod": {
 "type": "string",
 "enum": ["credit_card", "bank_transfer", "paypal"]
 },
 "cardNumber": { "type": "string" },
 "accountNumber": { "type": "string" },
 "paypalEmail": { "type": "string", "format": "email" }
 },
 "required": ["paymentMethod"],
 "if": {
 "properties": { "paymentMethod": { "const": "credit_card" } }
 },
 "then": {
 "required": ["cardNumber"]
 },
 "else": {
 "if": {
 "properties": { "paymentMethod": { "const": "bank_transfer" } }
 },
 "then": {
 "required": ["accountNumber"]
 },
 "else": {
 "required": ["paypalEmail"]
 }
 }
}

OneOf (Union Types)

Accept one of several possible schemas.

{
 "description": "Search filter - either by ID or by criteria",
 "oneOf": [
 {
 "type": "object",
 "description": "Search by ID",
 "properties": {
 "id": { "type": "string" }
 },
 "required": ["id"],
 "additionalProperties": false
 },
 {
 "type": "object",
 "description": "Search by criteria",
 "properties": {
 "name": { "type": "string" },
 "category": { "type": "string" },
 "minPrice": { "type": "number" },
 "maxPrice": { "type": "number" }
 },
 "anyOf": [
 { "required": ["name"] },
 { "required": ["category"] },
 { "required": ["minPrice"] }
 ],
 "additionalProperties": false
 }
 ]
}

Common Schema Patterns

📄 Pagination Parameters

{
 "type": "object",
 "properties": {
 "page": {
 "type": "integer",
 "description": "Page number (1-based)",
 "minimum": 1,
 "default": 1
 },
 "limit": {
 "type": "integer",
 "description": "Number of items per page",
 "minimum": 1,
 "maximum": 100,
 "default": 20
 },
 "sortBy": {
 "type": "string",
 "description": "Field to sort by",
 "enum": ["created_at", "updated_at", "name", "price"]
 },
 "sortOrder": {
 "type": "string",
 "description": "Sort direction",
 "enum": ["asc", "desc"],
 "default": "desc"
 }
 }
}

📅 Date Range Filtering

{
 "type": "object",
 "properties": {
 "startDate": {
 "type": "string",
 "format": "date",
 "description": "Start date (YYYY-MM-DD)"
 },
 "endDate": {
 "type": "string",
 "format": "date",
 "description": "End date (YYYY-MM-DD)"
 }
 },
 "if": {
 "properties": {
 "startDate": { "type": "string" },
 "endDate": { "type": "string" }
 },
 "required": ["startDate", "endDate"]
 },
 "then": {
 "properties": {
 "startDate": {
 "formatMaximum": { "$data": "1/endDate" }
 }
 }
 }
}

📁 File Data

{
 "type": "object",
 "properties": {
 "fileData": {
 "type": "string",
 "description": "Base64 encoded file content or raw text",
 "maxLength": 1048576 // 1MB limit
 },
 "fileName": {
 "type": "string",
 "description": "Original file name",
 "pattern": "^[^/\\\\:*?\"<>|]+$"
 },
 "mimeType": {
 "type": "string",
 "description": "File MIME type",
 "enum": [
 "text/plain",
 "text/csv",
 "application/json",
 "application/pdf",
 "image/jpeg",
 "image/png"
 ]
 }
 },
 "required": ["fileData", "fileName", "mimeType"]
}

Standard Response Formats

While input schemas are enforced, consistent response formats improve AI integration.

✅ Success Response

{
 "success": true,
 "data": {
 // Your actual response data
 "users": [...],
 "total": 156
 },
 "metadata": {
 "executionTime": "245ms",
 "timestamp": "2024-01-15T10:30:00Z",
 "version": "1.0"
 }
}

❌ Error Response

{
 "success": false,
 "error": "User not found with the provided email address",
 "code": "USER_NOT_FOUND",
 "details": {
 "field": "email",
 "value": "invalid@example.com",
 "suggestion": "Check the email spelling or try a different address"
 },
 "metadata": {
 "timestamp": "2024-01-15T10:30:00Z"
 }
}

Schema Validation Tips

Performance Tips

• Keep schemas as simple as possible while meeting your needs
• Use maxLength and maxItems to prevent abuse
• Prefer enum over complex pattern matching when possible
• Set reasonable defaults to reduce required parameters

AI-Friendly Tips

• Write clear descriptions that explain the purpose of each field
• Include examples in descriptions when helpful
• Use descriptive property names instead of abbreviations
• Group related parameters into nested objects

Next Steps

Tool Development

Apply schemas to build robust MCP tools

Tool Development Guide →

Design Patterns

Common schema patterns for different use cases

Pattern Library →

JSON Schema Docs

Official JSON Schema documentation

Learn JSON Schema →

Validation Testing

Test your schemas with online validators

Schema Validator →