Home

Schema.org MCP Server Documentation

Complete documentation for the Schema.org MCP Server with API key authentication and external HTTPS access.

Overview

The Schema.org MCP Server is a Model Context Protocol (MCP) server that provides access to the complete schema.org vocabulary. It enables AI assistants (like Claude) and applications to:

  • Query schema.org type definitions
  • Search for schema types by keyword
  • Explore type hierarchies and inheritance
  • List all properties for a type
  • Generate example JSON-LD markup

The server is deployed externally with HTTPS support and API key authentication at:

Base URL: https://json-ld-schema-mcp.serptransformer.com

Key Features

✅ Secure External Access - HTTPS with SSL/TLS encryption
✅ API Key Authentication - Secure access control
✅ Multiple Integration Methods - Claude Desktop, Node.js, Python, web apps, cURL
✅ Complete Documentation - Setup, endpoints, integration examples
✅ Production Ready - Systemd service, NGINX reverse proxy, monitoring
✅ SSE Transport - Server-Sent Events for real-time communication

Quick Start

1. Deploy the Server

cd /home/ubuntu/CascadeProjects/schema-org-mcp
sudo ./quick-start.sh

See Complete Setup Guide for detailed instructions.

2. Get Your API Key

On first startup, the server logs a default API key:

sudo journalctl -u schema-org-mcp | grep "Default API key"

3. Test the Server

API_KEY="sk_your_api_key"
 
# Health check
curl https://json-ld-schema-mcp.serptransformer.com/health
 
# List API keys
curl -H "Authorization: Bearer $API_KEY" \
  https://json-ld-schema-mcp.serptransformer.com/api-keys

4. Integrate with Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "schema-org": {
      "url": "https://json-ld-schema-mcp.serptransformer.com",
      "headers": {
        "Authorization": "Bearer sk_your_api_key"
      }
    }
  }
}

Restart Claude Desktop and start using schema.org tools!

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    External Clients                         │
│  (Claude Desktop, Node.js, Python, Web Apps, cURL, etc)    │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTPS
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   NGINX Reverse Proxy                       │
│        json-ld-schema-mcp.serptransformer.com              │
│  (SSL/TLS, CORS, Connection Pooling, Load Balancing)       │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP (localhost:3000)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Schema.org MCP Server (SSE)                    │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  GET /sse - SSE connection (requires API key)        │  │
│  │  POST /messages - Message POST (requires API key)    │  │
│  │  GET /health - Health check (no auth)                │  │
│  │  GET /api-keys - List keys (requires API key)        │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  Available Tools:                                            │
│  • get_schema_type                                          │
│  • search_schemas                                           │
│  • get_type_hierarchy                                       │
│  • get_type_properties                                      │
│  • generate_example                                         │
└─────────────────────────────────────────────────────────────┘

Documentation Sections

Setup & Deployment

API Reference

Integration

Available Tools

1. get_schema_type

Get detailed information about a schema.org type.

Example:

curl -H "Authorization: Bearer sk_your_api_key" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_schema_type","arguments":{"typeName":"Person"}}}' \
  https://json-ld-schema-mcp.serptransformer.com/messages

2. search_schemas

Search for schema types by keyword.

3. get_type_hierarchy

Get the inheritance hierarchy for a type.

4. get_type_properties

Get all properties available for a type.

5. generate_example

Generate example JSON-LD for a type.

Implementation Summary

Server Code Changes

  • Added auth.ts with ApiKeyManager class for API key management
  • Modified index.ts to integrate API key authentication
  • API keys stored in .api-keys.json with secure file permissions (0600)
  • Default key auto-generated on first run
  • Support for three authentication methods: Authorization header, X-API-Key header, query parameter

Key Features

  • ✅ Secure API key authentication on protected endpoints
  • ✅ Public health endpoint (no auth required)
  • ✅ API key listing endpoint for management
  • ✅ CORS headers properly configured
  • ✅ Error responses with appropriate HTTP status codes
  • ✅ Environment variable control (REQUIRE_AUTH)

Documentation Coverage

  • Setup from scratch to production deployment
  • All endpoints with examples
  • API key generation, management, and revocation
  • Integration with Claude Desktop, Node.js, Python, web apps, and CLI
  • Security best practices
  • Troubleshooting guides
  • Monitoring and maintenance procedures

Next Steps

  1. Review Documentation - Explore the sidebar for detailed guides
  2. Deploy Server - Follow the Complete Setup Guide
  3. Get API Key - Retrieve your authentication key
  4. Test Integration - Try with cURL, Python, or Node.js
  5. Integrate with Claude - Add to Claude Desktop configuration

Support Resources

Complete Setup