MCP Schema Documentation

How MCPify transforms your API into rich, self-documenting MCP tools

The Model Context Protocol (MCP) uses JSON Schema to describe tools, their inputs, outputs, and capabilities. MCPify automatically generates comprehensive MCP schemas from your existing API specifications, enriching them with metadata that helps AI agents make intelligent decisions.

Schema Components

Tool Definition

Each API endpoint becomes an MCP tool with a unique name, description, and schema:

{
  "name": "crm_list_contacts",
  "title": "List CRM Contacts",
  "description": "GET /api/v1/contacts - Retrieve a paginated list of contacts with optional filtering by status, tags, and creation date. Returns contact objects with full profile information.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "page": {
        "type": "integer",
        "minimum": 1,
        "default": 1,
        "description": "Page number for pagination"
      },
      "page_size": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20,
        "description": "Number of items per page"
      },
      "status": {
        "type": "string",
        "enum": ["active", "inactive", "pending"],
        "description": "Filter by contact status"
      },
      "created_after": {
        "type": "string",
        "format": "date-time",
        "description": "Filter contacts created after this date"
      }
    }
  }
}

Output Schema

MCPify generates detailed output schemas so agents know exactly what to expect:

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Contact"
        },
        "description": "Array of contact objects"
      },
      "pagination": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "page_size": { "type": "integer" },
          "total_pages": { "type": "integer" },
          "total_items": { "type": "integer" },
          "has_next": { "type": "boolean" },
          "has_previous": { "type": "boolean" }
        }
      },
      "meta": {
        "type": "object",
        "properties": {
          "cached": { "type": "boolean" },
          "cache_ttl_seconds": { "type": "integer" },
          "response_time_ms": { "type": "number" }
        }
      }
    },
    "required": ["data", "pagination", "meta"]
  }
}

Rich Metadata

Every tool includes extensive metadata for intelligent agent planning:

{
  "metadata": {
    "method": "GET",
    "path": "/api/v1/contacts",
    "category": "CRM",
    "tags": ["contacts", "read", "list"],
    "examples": [
      {
        "title": "List active contacts",
        "input": { "status": "active", "page_size": 10 },
        "output": { "data": [...], "pagination": {...} }
      }
    ],
    "errors": {
      "400": "Invalid request parameters",
      "401": "Authentication required",
      "429": "Rate limit exceeded",
      "500": "Internal server error"
    },
    "performance": {
      "p50_latency_ms": 120,
      "p95_latency_ms": 450,
      "p99_latency_ms": 1200,
      "typical_token_count": 850
    },
    "rate_limits": {
      "requests_per_minute": 60,
      "requests_per_hour": 1000,
      "burst_limit": 10
    },
    "caching": {
      "ttl_seconds": 300,
      "invalidation_events": ["contact_created", "contact_updated"],
      "cache_key_params": ["status", "page", "page_size"]
    },
    "cost": {
      "price_per_call_usd": 0.0002,
      "price_per_1k_tokens": 0.001
    }
  }
}

Schema Generation Process

Import API Specification

MCPify ingests your OpenAPI, GraphQL, or custom API documentation

Analyze Endpoints

Each endpoint is analyzed for parameters, request/response shapes, and relationships

Generate Tool Definitions

Endpoints are converted to MCP tools with descriptive names and comprehensive documentation

Enrich with Metadata

Performance metrics, rate limits, caching rules, and examples are added

Validate & Optimize

Schemas are validated and optimized for token efficiency

Publish to Gateway

Final schemas are deployed to the MCPify gateway for agent access

Advanced Schema Features

Relationship Mapping

MCPify identifies and documents relationships between entities

Foreign key relationships
Nested object structures
Reference resolution

Pagination Strategies

Automatic detection and documentation of pagination patterns

Cursor-based pagination
Offset/limit pagination
Page number pagination

Type Inference

Smart type detection from responses and documentation

Nullable field detection
Format validation (email, URL, UUID)
Enum extraction

Example Generation

Automatic creation of realistic examples for each tool

Valid request examples
Expected response samples
Error case examples

Customizing Generated Schemas

While MCPify generates comprehensive schemas automatically, you can customize them to match your specific needs:

// mcpify.config.js
export default {
  schemaGeneration: {
    // Add custom metadata to all tools
    globalMetadata: {
      department: "Engineering",
      compliance: ["SOC2", "GDPR"]
    },
    
    // Override specific tool configurations
    toolOverrides: {
      "crm_list_contacts": {
        description: "Custom description for the list contacts tool",
        metadata: {
          priority: "high",
          sla_ms: 500
        }
      }
    },
    
    // Custom naming strategy
    naming: {
      strategy: "snake_case", // or "camelCase", "kebab-case"
      prefix: "api_",
      removeVerbs: false
    },
    
    // Schema enrichment rules
    enrichment: {
      inferExamples: true,
      detectRelationships: true,
      generateMockData: true,
      includeDeprecated: false
    }
  }
}

Schema Best Practices

✅ Do's

• Provide detailed descriptions for all parameters
• Include realistic examples for complex operations
• Document all possible error responses
• Specify clear constraints (min/max, required fields)
• Use consistent naming conventions
• Include performance and cost metadata

❌ Don'ts

• Don't use ambiguous parameter names
• Don't omit error documentation
• Don't forget pagination limits
• Don't ignore deprecated fields
• Don't use inconsistent date formats
• Don't skip validation rules