MCPShield Documentation
Welcome to MCPShield, the professional protection service for Model Context Protocol (MCP) endpoints. This documentation will guide you through setting up and using MCPShield to secure your MCP servers.
Quick Start: Register your domain → Verify email → Copy SDK → Start protecting your MCP endpoints in under 5 minutes.
What is MCPShield?
MCPShield is a security proxy service that sits between your client applications and MCP servers, providing:
- Authentication: HMAC-SHA256 signed requests
- Authorization: Domain and method-level access control
- Rate Limiting: Configurable request throttling
- Monitoring: Usage analytics and security logging
- Protection: IP masking and DDoS mitigation
Registration Process
Getting started with MCPShield requires email verification for security:
1. Initial Registration
curl -X POST https://x0rg.org/api/register \
-H "Content-Type: application/json" \
-d '{
"email": "your@email.com",
"domain": "https://your-app.com",
"mcp_url": "https://your-mcp-server.com:8080",
"allowed_methods": ["run", "status", "health"],
"rate_limit": 50
}'
2. Email Verification
Check your email for a verification link. Click it to activate your account.
Important: Verification links expire after 1 hour. If expired, you'll need to register again.
3. Dashboard Access
After verification, you'll receive dashboard access with your SDK integration code.
SDK Integration
Once registered and verified, integrate the MCPShield SDK into your application:
Basic HTML Integration
<!-- Add to your HTML head -->
<meta http-equiv="Content-Security-Policy"
content="default-src 'self'; script-src 'self' https://x0rg.org; connect-src 'self';">
<!-- Add before closing </body> tag -->
<script src="https://x0rg.org/sdk/sdk-YOUR_TOKEN.js"></script>
<script>
document.addEventListener('DOMContentLoaded', async () => {
try {
const status = await MCP.call("status");
console.log("MCP Status:", status);
} catch (error) {
console.error("MCP Error:", error);
}
});
</script>
React Integration
import { useEffect, useState } from 'react';
function MCPComponent() {
const [mcpStatus, setMcpStatus] = useState('loading');
const [result, setResult] = useState(null);
useEffect(() => {
const script = document.createElement('script');
script.src = 'https://x0rg.org/sdk/sdk-YOUR_TOKEN.js';
script.onload = () => checkStatus();
document.head.appendChild(script);
return () => document.head.removeChild(script);
}, []);
const checkStatus = async () => {
try {
await window.MCP.call('status');
setMcpStatus('connected');
} catch (error) {
setMcpStatus('error');
}
};
const runTask = async () => {
try {
const result = await window.MCP.call('run', {
prompt: 'Hello MCP!'
});
setResult(result);
} catch (error) {
console.error('Task failed:', error);
}
};
return (
<div>
<p>Status: {mcpStatus}</p>
{mcpStatus === 'connected' && (
<button onClick={runTask}>Run Task</button>
)}
{result && <pre>{JSON.stringify(result, null, 2)}</pre>}
</div>
);
}
SDK Reference
The MCPShield SDK provides a simple interface for making secure MCP calls:
MCP.call(method, params)
Make a secure call to your MCP server
| Parameter | Type | Description |
|---|---|---|
| method | string | MCP method name (must be in allowed_methods) |
| params | object | Optional parameters for the MCP method |
// Basic usage
const result = await MCP.call('status');
// With parameters
const result = await MCP.call('run', {
prompt: 'Analyze this data',
timeout: 30,
format: 'json'
});
Common Methods
status
Check if your MCP server is responding
const status = await MCP.call('status');
console.log('Server healthy:', status.healthy);
run
Execute a task on your MCP server
const result = await MCP.call('run', {
prompt: 'What is the weather like?',
parameters: {
location: 'San Francisco',
units: 'metric'
}
});
health
Perform detailed health check with metrics
const health = await MCP.call('health', {
include_metrics: true,
check_dependencies: true
});
Security Features
MCPShield implements multiple layers of security:
Request Signing
All requests are signed with HMAC-SHA256 using your client-specific secret key:
// Automatic signature generation (handled by SDK)
signature = HMAC-SHA256(
key: client_secret,
message: method + params + timestamp + fingerprint + nonce
)
Domain Validation
Requests are validated against your registered domain to prevent unauthorized usage.
Rate Limiting
Configurable rate limits prevent abuse and ensure fair usage:
- Per-client limits
- Sliding window algorithm
- Method-specific limits (optional)
- Burst protection
Browser Security
The SDK includes multiple browser-based security measures:
- DevTools Detection: Automatically detects when developer tools are open
- Fingerprinting: Creates unique browser fingerprints to detect anomalies
- Environment Validation: Ensures SDK runs in authorized environments
Security Notice: The SDK will automatically shut down if it detects developer tools or unauthorized modifications.
Integration Examples
Error Handling with Retry Logic
async function callMCPWithRetry(method, params, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await MCP.call(method, params);
} catch (error) {
if (error.message.includes('Rate limit') && attempt < maxRetries) {
// Wait before retrying rate limit errors
await new Promise(resolve =>
setTimeout(resolve, 1000 * attempt)
);
continue;
}
console.error(`MCP call failed (attempt ${attempt}):`, {
method,
error: error.message,
params
});
if (attempt === maxRetries) {
throw error; // Final attempt failed
}
}
}
}
// Usage
try {
const result = await callMCPWithRetry('run', { prompt: 'test' });
console.log('Success:', result);
} catch (error) {
showUserError('Service temporarily unavailable');
}
Vue.js Integration
<template>
<div>
<div v-if="status === 'loading'">Connecting to MCP...</div>
<div v-else-if="status === 'connected'">
<button @click="runTask">Run Task</button>
<pre v-if="result">{{ result }}</pre>
</div>
<div v-else>Connection failed</div>
</div>
</template>
<script>
export default {
data() {
return {
status: 'loading',
result: null
}
},
async mounted() {
try {
// Load MCPShield SDK
await this.loadSDK();
await window.MCP.call('status');
this.status = 'connected';
} catch (error) {
this.status = 'error';
console.error('MCP connection failed:', error);
}
},
methods: {
loadSDK() {
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.src = 'https://x0rg.org/sdk/sdk-YOUR_TOKEN.js';
script.onload = resolve;
script.onerror = reject;
document.head.appendChild(script);
});
},
async runTask() {
try {
this.result = await window.MCP.call('run', {
prompt: 'Hello from Vue!'
});
} catch (error) {
console.error('Task failed:', error);
}
}
}
}
</script>
Troubleshooting
Common Issues
Invalid client error
Cause: Client ID not found or account not activated
Solution: Verify your email and ensure account is activated
Solution: Verify your email and ensure account is activated
Rate limit exceeded
Cause: Too many requests in the time window
Solution: Implement exponential backoff or upgrade rate limits
Solution: Implement exponential backoff or upgrade rate limits
Method not allowed
Cause: Calling a method not in your allowed_methods list
Solution: Update your allowed methods in the dashboard
Solution: Update your allowed methods in the dashboard
Unauthorized domain
Cause: Request coming from a domain not matching your registration
Solution: Ensure your domain matches exactly (including protocol)
Solution: Ensure your domain matches exactly (including protocol)
Debug Mode
Enable additional logging to troubleshoot issues:
// Enable debug logging (development only)
window.MCP_DEBUG = true;
// All MCP calls will now log detailed information
const result = await MCP.call('status');
Security Warning: Never enable debug mode in production as it may expose sensitive information.
API Reference
Direct API endpoints for advanced integrations:
Registration
POST https://x0rg.org/api/register
Content-Type: application/json
{
"email": "user@example.com",
"domain": "https://myapp.com",
"mcp_url": "https://mcp-server.com:8080",
"allowed_methods": ["run", "status"],
"rate_limit": 20
}
Login
POST https://x0rg.org/api/login
Content-Type: application/json
{
"email": "user@example.com"
}
Dashboard Data
GET https://x0rg.org/api/dashboard?token=DASHBOARD_TOKEN
MCP Proxy
POST https://x0rg.org/mcp-proxy
Content-Type: application/json
X-MCP-Signature: HMAC_SHA256_SIGNATURE
X-MCP-Client: CLIENT_ID
X-MCP-Method: METHOD_NAME
X-MCP-Timestamp: TIMESTAMP
{
"method": "run",
"params": { "prompt": "Hello" },
"id": "request-id"
}