Complete Setup

Complete Setup and Deployment Guide

Table of Contents

  1. Prerequisites
  2. Initial Setup
  3. SSL Certificate Setup
  4. Server Deployment
  5. NGINX Configuration
  6. Verification
  7. API Key Management
  8. Integration Methods
  9. Troubleshooting

Prerequisites

System Requirements

  • Ubuntu 20.04 LTS or later
  • Node.js 18+
  • NGINX 1.18+
  • Sudo access
  • Domain: json-ld-schema-mcp.serptransformer.com

Install Dependencies

# Update system
sudo apt update
sudo apt upgrade -y
 
# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
 
# Install NGINX
sudo apt install -y nginx
 
# Install Certbot for SSL
sudo apt install -y certbot python3-certbot-nginx
 
# Verify installations
node --version
npm --version
nginx -v
certbot --version

Initial Setup

1. Clone and Prepare Project

cd /home/ubuntu/CascadeProjects/schema-org-mcp
npm install
npm run build

2. Verify Build

ls -la dist/
# Should show: index.js, schema-org-client.js, auth.js

3. Test Locally (Optional)

# Test in stdio mode
node dist/index.js
 
# Or test in SSE mode (Ctrl+C to stop)
USE_SSE=true SSE_PORT=3000 node dist/index.js &
sleep 2
curl http://localhost:3000/health
pkill -f "node dist/index.js"

SSL Certificate Setup

1. Stop NGINX Temporarily

sudo systemctl stop nginx

2. Obtain Certificate from Let's Encrypt

sudo certbot certonly --standalone \
  -d json-ld-schema-mcp.serptransformer.com \
  --agree-tos \
  --no-eff-email \
  -m your-email@example.com

3. Verify Certificate

sudo ls -la /etc/letsencrypt/live/json-ld-schema-mcp.serptransformer.com/

Expected files:

  • fullchain.pem - Full certificate chain
  • privkey.pem - Private key
  • cert.pem - Certificate
  • chain.pem - Intermediate certificates

4. Set Up Auto-Renewal

sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer
 
# Test renewal (dry-run)
sudo certbot renew --dry-run

Server Deployment

1. Install Systemd Service

sudo cp /home/ubuntu/CascadeProjects/schema-org-mcp/schema-org-mcp.service \
  /etc/systemd/system/
 
sudo systemctl daemon-reload
sudo systemctl enable schema-org-mcp

2. Verify Service File

sudo cat /etc/systemd/system/schema-org-mcp.service

Should show:

[Unit]
Description=Schema.org MCP Server
After=network.target
 
[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/CascadeProjects/schema-org-mcp
Environment="USE_SSE=true"
Environment="SSE_PORT=3000"
ExecStart=/usr/bin/node /home/ubuntu/CascadeProjects/schema-org-mcp/dist/index.js
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
 
[Install]
WantedBy=multi-user.target

3. Start the Service

sudo systemctl start schema-org-mcp

4. Verify Service is Running

sudo systemctl status schema-org-mcp
 
# Should show: Active: active (running)

5. Check Logs

sudo journalctl -u schema-org-mcp -n 20
 
# Should show:
# Schema.org MCP server running on SSE at http://0.0.0.0:3000
# SSE endpoint: http://0.0.0.0:3000/sse
# Messages endpoint: http://0.0.0.0:3000/messages
# Health check: http://0.0.0.0:3000/health
# API Keys endpoint: http://0.0.0.0:3000/api-keys
# Authentication: ENABLED

6. Get Default API Key

sudo journalctl -u schema-org-mcp | grep "Default API key"
 
# Copy the key (format: sk_...)

NGINX Configuration

1. Copy NGINX Config

sudo cp /home/ubuntu/CascadeProjects/schema-org-mcp/nginx-schema-org-mcp.conf \
  /etc/nginx/sites-available/

2. Enable Site

sudo ln -s /etc/nginx/sites-available/nginx-schema-org-mcp.conf \
  /etc/nginx/sites-enabled/

3. Verify Configuration

sudo nginx -t
 
# Should show:
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

4. Start NGINX

sudo systemctl start nginx
sudo systemctl enable nginx

5. Verify NGINX is Running

sudo systemctl status nginx

Verification

1. Health Check (No Auth Required)

curl https://json-ld-schema-mcp.serptransformer.com/health
 
# Response:
# {"status":"ok"}

2. Check SSL Certificate

openssl s_client -connect json-ld-schema-mcp.serptransformer.com:443 -brief
 
# Should show: CONNECTED

3. Test with API Key

API_KEY="sk_your_api_key_from_logs"
 
# List API keys
curl -H "Authorization: Bearer $API_KEY" \
  https://json-ld-schema-mcp.serptransformer.com/api-keys
 
# Response:
# {"keys":[{"name":"default-key","enabled":true,...}]}

4. Check NGINX Logs

sudo tail -f /var/log/nginx/schema-org-mcp-access.log
sudo tail -f /var/log/nginx/schema-org-mcp-error.log

API Key Management

1. Locate API Keys File

cat /home/ubuntu/CascadeProjects/schema-org-mcp/.api-keys.json

2. View Current Keys

API_KEY="sk_your_default_key"
 
curl -H "Authorization: Bearer $API_KEY" \
  https://json-ld-schema-mcp.serptransformer.com/api-keys

3. Add New Key

Edit .api-keys.json:

sudo nano /home/ubuntu/CascadeProjects/schema-org-mcp/.api-keys.json

Add a new entry:

{
  "sk_existing_key...": { ... },
  "sk_newkey1234567890abcdef...": {
    "key": "sk_newkey1234567890abcdef...",
    "name": "production-key",
    "enabled": true,
    "createdAt": "2025-12-23T07:30:00.000Z",
    "rateLimit": 1000
  }
}

Save and restart:

sudo systemctl restart schema-org-mcp

4. Revoke a Key

Edit .api-keys.json and set "enabled": false:

{
  "sk_oldkey...": {
    "key": "sk_oldkey...",
    "name": "old-key",
    "enabled": false,
    "createdAt": "2025-12-23T06:00:00.000Z"
  }
}

Restart:

sudo systemctl restart schema-org-mcp

Integration Methods

Method 1: Claude Desktop

Configuration

Edit ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Usage

Once configured, Claude will have access to all schema.org tools in conversations.

Method 2: Node.js Client

Installation

npm install @modelcontextprotocol/sdk

Code Example

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 
const apiKey = process.env.SCHEMA_ORG_API_KEY;
 
const transport = new SSEClientTransport({
  url: 'https://json-ld-schema-mcp.serptransformer.com/sse',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
  },
});
 
const client = new Client({
  name: 'schema-org-client',
  version: '1.0.0',
}, {
  capabilities: {},
});
 
await client.connect(transport);
 
// Get schema type
const result = await client.callTool({
  name: 'get_schema_type',
  arguments: { typeName: 'Person' },
});
 
console.log(result);

Usage

SCHEMA_ORG_API_KEY="sk_your_api_key" node client.js

Method 3: Python Client

Installation

pip install requests sseclient-py

Code Example

import requests
from sseclient import SSEClient
import os
import json
 
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 get_schema_type(self, type_name):
        """Get schema type information"""
        message = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "get_schema_type",
                "arguments": {"typeName": type_name}
            }
        }
        response = requests.post(
            f"{self.base_url}/messages",
            headers=self.headers,
            json=message
        )
        return response.json()
    
    def search_schemas(self, query, limit=10):
        """Search for schema types"""
        message = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "search_schemas",
                "arguments": {"query": query, "limit": limit}
            }
        }
        response = requests.post(
            f"{self.base_url}/messages",
            headers=self.headers,
            json=message
        )
        return response.json()
 
# Usage
api_key = os.getenv('SCHEMA_ORG_API_KEY')
mcp = SchemaOrgMCP(api_key)
 
print("Health:", mcp.health_check())
print("Person Type:", mcp.get_schema_type("Person"))
print("Search Results:", mcp.search_schemas("article", limit=5))

Usage

SCHEMA_ORG_API_KEY="sk_your_api_key" python client.py

Method 4: cURL

Basic Examples

API_KEY="sk_your_api_key"
BASE_URL="https://json-ld-schema-mcp.serptransformer.com"
 
# Health check (no auth)
curl $BASE_URL/health
 
# List API keys
curl -H "Authorization: Bearer $API_KEY" \
  $BASE_URL/api-keys
 
# Get schema type (via SSE)
curl -N -H "Authorization: Bearer $API_KEY" \
  $BASE_URL/sse

Troubleshooting

Service Won't Start

# Check status
sudo systemctl status schema-org-mcp
 
# View logs
sudo journalctl -u schema-org-mcp -n 50
 
# Try running manually
USE_SSE=true SSE_PORT=3000 node /home/ubuntu/CascadeProjects/schema-org-mcp/dist/index.js

NGINX Connection Issues

# Test configuration
sudo nginx -t
 
# Check if port 3000 is listening
sudo netstat -tlnp | grep 3000
 
# Test upstream directly
curl -v http://127.0.0.1:3000/health
 
# Check NGINX error log
sudo tail -f /var/log/nginx/schema-org-mcp-error.log

SSL Certificate Issues

# Check certificate validity
sudo openssl x509 -in /etc/letsencrypt/live/json-ld-schema-mcp.serptransformer.com/fullchain.pem -text -noout
 
# Test SSL connection
openssl s_client -connect json-ld-schema-mcp.serptransformer.com:443
 
# Renew certificate
sudo certbot renew --force-renewal

API Key Issues

# Check API keys file
cat /home/ubuntu/CascadeProjects/schema-org-mcp/.api-keys.json
 
# Verify file permissions
ls -la /home/ubuntu/CascadeProjects/schema-org-mcp/.api-keys.json
# Should be: -rw------- (600)
 
# Reset to default key
sudo systemctl stop schema-org-mcp
rm /home/ubuntu/CascadeProjects/schema-org-mcp/.api-keys.json
sudo systemctl start schema-org-mcp
sudo journalctl -u schema-org-mcp -n 5 | grep "Default API key"

DNS Resolution Issues

# Check DNS
nslookup json-ld-schema-mcp.serptransformer.com
dig json-ld-schema-mcp.serptransformer.com
 
# Test from different DNS servers
nslookup json-ld-schema-mcp.serptransformer.com 8.8.8.8

Monitoring and Maintenance

View Live Logs

# MCP Server logs
sudo journalctl -u schema-org-mcp -f
 
# NGINX access logs
sudo tail -f /var/log/nginx/schema-org-mcp-access.log
 
# NGINX error logs
sudo tail -f /var/log/nginx/schema-org-mcp-error.log

Restart Services

# Restart MCP server
sudo systemctl restart schema-org-mcp
 
# Restart NGINX
sudo systemctl reload nginx
 
# Restart both
sudo systemctl restart schema-org-mcp nginx

Check Service Status

# MCP server
sudo systemctl status schema-org-mcp
 
# NGINX
sudo systemctl status nginx
 
# Both
sudo systemctl status schema-org-mcp nginx

Backup Configuration

# Create backup
sudo tar -czf ~/schema-org-mcp-backup-$(date +%Y%m%d).tar.gz \
  /home/ubuntu/CascadeProjects/schema-org-mcp/.api-keys.json \
  /etc/nginx/sites-available/nginx-schema-org-mcp.conf \
  /etc/systemd/system/schema-org-mcp.service
 
# List backups
ls -lh ~/schema-org-mcp-backup-*.tar.gz

Restore from Backup

# Extract backup
sudo tar -xzf ~/schema-org-mcp-backup-YYYYMMDD.tar.gz -C /
 
# Reload systemd
sudo systemctl daemon-reload
 
# Restart services
sudo systemctl restart schema-org-mcp nginx

Security Checklist

  • SSL certificate installed and valid
  • API keys generated and stored securely
  • .api-keys.json has permissions 0600
  • NGINX HTTPS redirect enabled
  • Security headers configured
  • CORS headers set appropriately
  • Firewall allows only 80 and 443
  • Regular certificate renewal enabled
  • Logs monitored regularly
  • Backups created regularly

Next Steps

  1. Review Documentation

  2. Test Integration

    • Test with cURL
    • Test with Python client
    • Test with Node.js client
    • Test with Claude Desktop

  3. Monitor Production

    • Set up log rotation
    • Monitor disk space
    • Track API usage
    • Monitor certificate expiration

  4. Optimize Performance

    • Tune NGINX worker processes
    • Enable GZIP compression
    • Configure connection pooling
    • Monitor response times
HomeAPI Authentication