API Endpoints

API Endpoints Reference

Base URL

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

Authentication

All protected endpoints require an API key. Include it using one of these methods:

Authorization Header (Recommended):

Authorization: Bearer sk_your_api_key

X-API-Key Header:

X-API-Key: sk_your_api_key

Query Parameter:

?api_key=sk_your_api_key

See API_AUTHENTICATION.md for details.

Endpoints

Health Check

Endpoint: GET /health

Authentication: Not required

Description: Check if the server is running and healthy.

Request:

curl https://json-ld-schema-mcp.serptransformer.com/health

Response (200 OK):

{
  "status": "ok"
}

SSE Connection

Endpoint: GET /sse

Authentication: Required

Description: Establishes a Server-Sent Events (SSE) connection for the MCP protocol. This endpoint streams messages from the server to the client.

Request:

curl -H "Authorization: Bearer sk_your_api_key" \
  https://json-ld-schema-mcp.serptransformer.com/sse

Response Headers:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Response Format:

data: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

data: {"jsonrpc":"2.0","id":2,"result":{...}}

Error Response (401 Unauthorized):

{
  "error": "Unauthorized: Invalid or missing API key"
}

Notes:

  • Connection remains open for streaming
  • Use for bidirectional communication with MCP server
  • Timeout: 3600 seconds (1 hour)

Messages Endpoint

Endpoint: POST /messages

Authentication: Required

Description: Send messages to the MCP server. Used in conjunction with the SSE endpoint for request/response communication.

Request:

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

Request Body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Response (200 OK):

{
  "success": true
}

Error Response (401 Unauthorized):

{
  "error": "Unauthorized: Invalid or missing API key"
}

Error Response (400 Bad Request):

{
  "error": "Invalid JSON"
}

API Keys Management

Endpoint: GET /api-keys

Authentication: Required

Description: List all API keys associated with your account. Returns key names, status, creation time, and last usage.

Request:

curl -H "Authorization: Bearer sk_your_api_key" \
  https://json-ld-schema-mcp.serptransformer.com/api-keys

Response (200 OK):

{
  "keys": [
    {
      "name": "default-key",
      "enabled": true,
      "createdAt": "2025-12-23T07:00:00.000Z",
      "lastUsed": "2025-12-23T07:05:00.000Z"
    },
    {
      "name": "production-key",
      "enabled": true,
      "createdAt": "2025-12-23T06:00:00.000Z",
      "lastUsed": "2025-12-23T07:04:00.000Z",
      "rateLimit": 1000
    }
  ]
}

Error Response (401 Unauthorized):

{
  "error": "Unauthorized"
}

MCP Protocol Tools

Once connected via the SSE endpoint, the following tools are available:

1. get_schema_type

Get detailed information about a schema.org type.

Method: tools/call

Parameters:

{
  "name": "get_schema_type",
  "arguments": {
    "typeName": "Person"
  }
}

Response:

{
  "name": "Person",
  "description": "A person (alive, dead, undead, or fictional).",
  "id": "https://schema.org/Person",
  "type": "rdfs:Class",
  "superTypes": [
    {
      "name": "Thing",
      "id": "https://schema.org/Thing"
    }
  ],
  "url": "https://schema.org/Person"
}

2. search_schemas

Search for schema types by keyword.

Method: tools/call

Parameters:

{
  "name": "search_schemas",
  "arguments": {
    "query": "article",
    "limit": 5
  }
}

Response:

[
  {
    "name": "Article",
    "description": "An article, such as a news article or piece of investigative report.",
    "id": "https://schema.org/Article",
    "url": "https://schema.org/Article"
  },
  {
    "name": "NewsArticle",
    "description": "A news article.",
    "id": "https://schema.org/NewsArticle",
    "url": "https://schema.org/NewsArticle"
  }
]

3. get_type_hierarchy

Get the inheritance hierarchy for a schema.org type.

Method: tools/call

Parameters:

{
  "name": "get_type_hierarchy",
  "arguments": {
    "typeName": "NewsArticle"
  }
}

Response:

{
  "name": "NewsArticle",
  "id": "https://schema.org/NewsArticle",
  "parents": [
    {
      "name": "Article",
      "id": "https://schema.org/Article"
    },
    {
      "name": "Thing",
      "id": "https://schema.org/Thing"
    }
  ],
  "children": [
    {
      "name": "ReportageNewsArticle",
      "id": "https://schema.org/ReportageNewsArticle"
    }
  ]
}

4. get_type_properties

Get all properties available for a schema.org type.

Method: tools/call

Parameters:

{
  "name": "get_type_properties",
  "arguments": {
    "typeName": "Organization",
    "includeInherited": true
  }
}

Response:

[
  {
    "name": "name",
    "description": "The name of the item.",
    "id": "https://schema.org/name",
    "expectedTypes": ["Text"]
  },
  {
    "name": "description",
    "description": "A description of the item.",
    "id": "https://schema.org/description",
    "expectedTypes": ["Text"],
    "inheritedFrom": "Thing"
  },
  {
    "name": "address",
    "description": "Physical address of the item.",
    "id": "https://schema.org/address",
    "expectedTypes": ["PostalAddress", "Text"]
  }
]

5. generate_example

Generate an example JSON-LD for a schema.org type.

Method: tools/call

Parameters:

{
  "name": "generate_example",
  "arguments": {
    "typeName": "Recipe",
    "properties": {
      "name": "Chocolate Chip Cookies",
      "prepTime": "PT20M"
    }
  }
}

Response:

{
  "@context": "https://schema.org",
  "@type": "Recipe",
  "name": "Chocolate Chip Cookies",
  "description": "Example description",
  "prepTime": "PT20M",
  "url": "https://example.com"
}

HTTP Status Codes

CodeMeaningExample
200SuccessRequest processed successfully
204No ContentOPTIONS request handled
400Bad RequestInvalid JSON in request body
401UnauthorizedMissing or invalid API key
404Not FoundEndpoint does not exist
500Server ErrorInternal server error

Rate Limiting

Currently, rate limiting is not enforced. Future versions will support per-key rate limits configured in the API keys file.

CORS Headers

All responses include CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key

Request/Response Format

JSON-RPC 2.0 Format

The MCP protocol uses JSON-RPC 2.0 for tool calls:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_schema_type",
    "arguments": {
      "typeName": "Person"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...}"
      }
    ]
  }
}

Timeout Settings

EndpointTimeout
/sse3600 seconds (1 hour)
/messages30 seconds
/health10 seconds
/api-keys10 seconds

Examples

Complete SSE Connection Flow

#!/bin/bash
 
API_KEY="sk_your_api_key"
BASE_URL="https://json-ld-schema-mcp.serptransformer.com"
 
# 1. Check health
echo "Checking server health..."
curl -s "$BASE_URL/health" | jq .
 
# 2. List API keys
echo "Listing API keys..."
curl -s -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api-keys" | jq .
 
# 3. Establish SSE connection
echo "Connecting to SSE endpoint..."
curl -N -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/sse"

Python Integration

import requests
import json
from sseclient import SSEClient
 
class SchemaOrgMCP:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://json-ld-schema-mcp.serptransformer.com"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }
    
    def health_check(self):
        """Check server health"""
        response = requests.get(f"{self.base_url}/health")
        return response.json()
    
    def list_keys(self):
        """List API keys"""
        response = requests.get(
            f"{self.base_url}/api-keys",
            headers=self.headers
        )
        return response.json()
    
    def connect_sse(self):
        """Connect to SSE endpoint"""
        url = f"{self.base_url}/sse"
        client = SSEClient(url, headers=self.headers)
        return client
    
    def send_message(self, message):
        """Send message to server"""
        response = requests.post(
            f"{self.base_url}/messages",
            headers=self.headers,
            json=message
        )
        return response.json()
 
# Usage
mcp = SchemaOrgMCP("sk_your_api_key")
print(mcp.health_check())
print(mcp.list_keys())

Troubleshooting

Connection Refused

  • Verify the server is running: curl https://json-ld-schema-mcp.serptransformer.com/health
  • Check NGINX is properly configured
  • Verify DNS resolution

401 Unauthorized

  • Verify API key is correct
  • Check key is enabled in .api-keys.json
  • Ensure key is included in request headers
  • Use HTTPS (not HTTP)

400 Bad Request

  • Verify JSON is valid
  • Check Content-Type header is set to application/json
  • Ensure request body is properly formatted

Timeout

  • Check server logs: sudo journalctl -u schema-org-mcp -f
  • Verify network connectivity
  • Check firewall rules
API AuthenticationIntegration Guide