External Setup

External MCP Server Setup - Schema.org Implementation

Quick Summary

You now have a fully configured Schema.org MCP server ready for external deployment with NGINX reverse proxy support.

What Has Been Set Up

1. MCP Server with SSE Transport

  • Modified src/index.ts to support Server-Sent Events (SSE) for external HTTP/HTTPS access
  • Supports both stdio mode (local) and SSE mode (external)
  • Environment variables: USE_SSE=true and SSE_PORT=3000

2. Systemd Service

  • File: schema-org-mcp.service
  • Automatically starts on boot
  • Runs as non-root user (ubuntu)
  • Configured for SSE mode on port 3000

3. NGINX Reverse Proxy Configuration

  • File: nginx-schema-org-mcp.conf
  • Domain: json-ld-schema-mcp.serptransformer.com
  • SSL/TLS enabled (HTTPS only)
  • CORS headers configured
  • Connection pooling and keepalive enabled
  • Endpoints:
    • /health - Health check
    • /sse - SSE connection endpoint
    • /messages - Message POST endpoint

4. Documentation

  • DEPLOYMENT.md - Detailed deployment instructions
  • SETUP_GUIDE.md - Step-by-step setup walkthrough
  • CLIENT_EXAMPLE.md - Client integration examples
  • EXTERNAL_MCP_SETUP.md - This file

5. Quick Start Script

  • File: quick-start.sh
  • Automates installation and systemd setup
  • Usage: sudo ./quick-start.sh

Key Files Modified/Created

/home/ubuntu/CascadeProjects/schema-org-mcp/
├── src/
│   ├── index.ts (MODIFIED - Added SSE transport support)
│   └── schema-org-client.ts (unchanged)
├── dist/ (compiled output)
├── schema-org-mcp.service (NEW - Systemd service)
├── nginx-schema-org-mcp.conf (NEW - NGINX config)
├── quick-start.sh (NEW - Quick setup script)
├── DEPLOYMENT.md (NEW - Deployment guide)
├── SETUP_GUIDE.md (NEW - Complete setup walkthrough)
├── CLIENT_EXAMPLE.md (NEW - Client examples)
└── EXTERNAL_MCP_SETUP.md (NEW - This file)

Deployment Steps (Quick Reference)

Prerequisites

  • SSL certificate for json-ld-schema-mcp.serptransformer.com (via Let's Encrypt)
  • NGINX installed
  • Node.js 18+ installed
  • Sudo access

Installation

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

Manual Installation

# Install dependencies
npm install
npm run build
 
# Install systemd service
sudo cp schema-org-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable schema-org-mcp
 
# Configure NGINX
sudo cp nginx-schema-org-mcp.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/nginx-schema-org-mcp.conf /etc/nginx/sites-enabled/
 
# Verify and start
sudo nginx -t
sudo systemctl start schema-org-mcp
sudo systemctl reload nginx

Verification

# Test health endpoint
curl https://json-ld-schema-mcp.serptransformer.com/health
 
# Check service status
sudo systemctl status schema-org-mcp
 
# View logs
sudo journalctl -u schema-org-mcp -f

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    External Clients                         │
│              (Claude Desktop, Custom Apps, etc)             │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTPS
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   NGINX Reverse Proxy                       │
│        json-ld-schema-mcp.serptransformer.com              │
│  (SSL/TLS, CORS, Connection Pooling, Load Balancing)       │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP (localhost)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Schema.org MCP Server (SSE)                    │
│                    Port 3000                                │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  /sse endpoint - SSE connection                      │  │
│  │  /messages endpoint - Message POST                   │  │
│  │  /health endpoint - Health check                     │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  Available Tools:                                            │
│  • get_schema_type                                          │
│  • search_schemas                                           │
│  • get_type_hierarchy                                       │
│  • get_type_properties                                      │
│  • generate_example                                         │
└─────────────────────────────────────────────────────────────┘

Environment Variables

VariableDefaultPurpose
USE_SSEfalseEnable SSE mode for external access
SSE_PORT3000Port for SSE server

API Endpoints

Health Check

GET /health
Response: {"status":"ok"}

SSE Connection

GET /sse
Content-Type: text/event-stream

Message Endpoint

POST /messages
Content-Type: application/json

Available MCP Tools

  1. get_schema_type - Get detailed schema type information
  2. search_schemas - Search for schema types by keyword
  3. get_type_hierarchy - Get type inheritance relationships
  4. get_type_properties - List all properties for a type
  5. generate_example - Generate example JSON-LD

Security Features

✓ HTTPS/TLS encryption
✓ CORS headers configured
✓ Security headers (HSTS, X-Frame-Options, etc.)
✓ Non-root service execution
✓ Connection pooling and keepalive
✓ Input validation

Monitoring & Maintenance

View Logs

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

Restart Service

sudo systemctl restart schema-org-mcp

Check Status

sudo systemctl status schema-org-mcp

SSL Certificate Renewal

sudo certbot renew
sudo systemctl reload nginx

Integration Examples

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "schema-org": {
      "url": "https://json-ld-schema-mcp.serptransformer.com"
    }
  }
}

Node.js Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 
const transport = new SSEClientTransport({
  url: 'https://json-ld-schema-mcp.serptransformer.com/sse',
});
 
const client = new Client({...}, {...});
await client.connect(transport);

cURL

# Health check
curl https://json-ld-schema-mcp.serptransformer.com/health
 
# Establish SSE connection
curl -N https://json-ld-schema-mcp.serptransformer.com/sse

Troubleshooting

Service won't start

sudo journalctl -u schema-org-mcp -n 50
USE_SSE=true SSE_PORT=3000 node /home/ubuntu/CascadeProjects/schema-org-mcp/dist/index.js

NGINX connection issues

sudo nginx -t
sudo netstat -tlnp | grep 3000
curl -v http://127.0.0.1:3000/health

SSL certificate errors

sudo certbot certificates
openssl s_client -connect json-ld-schema-mcp.serptransformer.com:443

Performance Tuning

NGINX Connection Pool

Edit nginx-schema-org-mcp.conf:

upstream schema_org_mcp {
    server 127.0.0.1:3000;
    keepalive 64;  # Increase for higher concurrency
}

SSE Timeout

Edit nginx-schema-org-mcp.conf:

proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

Backup Strategy

# Create backup
sudo tar -czf ~/schema-org-mcp-backup-$(date +%Y%m%d).tar.gz \
  /home/ubuntu/CascadeProjects/schema-org-mcp \
  /etc/nginx/sites-available/nginx-schema-org-mcp.conf \
  /etc/systemd/system/schema-org-mcp.service
 
# Restore backup
sudo tar -xzf ~/schema-org-mcp-backup-YYYYMMDD.tar.gz -C /
sudo systemctl daemon-reload
sudo systemctl restart schema-org-mcp nginx

Next Steps

  1. Complete Setup: Follow SETUP_GUIDE.md for detailed instructions
  2. Test Integration: Use examples in CLIENT_EXAMPLE.md
  3. Monitor: Set up monitoring and alerting
  4. Optimize: Tune performance based on usage patterns
  5. Document: Keep deployment notes for your team

Support & Resources

Summary

Your Schema.org MCP server is now ready for external deployment. All necessary files, configurations, and documentation have been created. The server supports:

  • ✅ External HTTPS access via NGINX reverse proxy
  • ✅ SSE (Server-Sent Events) transport for MCP protocol
  • ✅ Systemd service management
  • ✅ SSL/TLS encryption
  • ✅ CORS support
  • ✅ Health monitoring
  • ✅ Comprehensive logging

Follow the SETUP_GUIDE.md to complete the deployment on your server.

Integration Guide