Diosc MCP Requirements

Diosc extends standard MCP with enterprise features. This page explains what your MCP server needs to work with Diosc.

Overview of Extensions

Feature	Standard MCP	Diosc MCP
Tool discovery	Yes	Yes
Tool execution	Yes	Yes
Authentication headers	Not specified	Required
Health endpoint	Not specified	Required
SSE transport	Optional	Required
Connection pooling	Client-side	Server-side support

Required: SSE Transport

Diosc connects to MCP servers using Server-Sent Events (SSE) over HTTP.

Endpoint Structure

Your MCP server must expose:

GET  /sse              → SSE event stream
POST /messages         → Handle MCP messages
GET  /health           → Health check (Diosc extension)

SSE Connection Flow

1. Diosc Hub connects:
   GET /sse
   Accept: text/event-stream

2. Server responds with stream:
   HTTP/1.1 200 OK
   Content-Type: text/event-stream

   event: endpoint
   data: /messages?sessionId=abc123

3. Diosc sends MCP messages:
   POST /messages?sessionId=abc123
   Content-Type: application/json

   { "method": "tools/list", ... }

4. Server responds via SSE:
   event: message
   data: { "tools": [...] }

Implementation Example (Node.js/Express)

import express from 'express';
import { randomUUID } from 'crypto';

const app = express();
const sessions = new Map();

// SSE endpoint
app.get('/sse', (req, res) => {
  const sessionId = randomUUID();

  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  // Store session for later message handling
  sessions.set(sessionId, { res, authHeaders: {} });

  // Send endpoint location
  res.write(`event: endpoint\ndata: /messages?sessionId=${sessionId}\n\n`);

  // Keep-alive ping every 30 seconds
  const pingInterval = setInterval(() => {
    res.write(': ping\n\n');
  }, 30000);

  req.on('close', () => {
    clearInterval(pingInterval);
    sessions.delete(sessionId);
  });
});

// Message endpoint
app.post('/messages', express.json(), async (req, res) => {
  const sessionId = req.query.sessionId as string;
  const session = sessions.get(sessionId);

  if (!session) {
    return res.status(404).json({ error: 'Session not found' });
  }

  // Store auth headers for tool calls
  session.authHeaders = extractAuthHeaders(req.headers);

  // Process MCP message
  const response = await handleMcpMessage(req.body, session.authHeaders);

  // Send response via SSE
  session.res.write(`event: message\ndata: ${JSON.stringify(response)}\n\n`);

  res.status(202).end();
});

function extractAuthHeaders(headers: any): Record<string, string> {
  const auth: Record<string, string> = {};
  if (headers.authorization) {
    auth['Authorization'] = headers.authorization;
  }
  // Extract X-User-* headers
  for (const [key, value] of Object.entries(headers)) {
    if (key.toLowerCase().startsWith('x-user-')) {
      auth[key] = value as string;
    }
  }
  return auth;
}

Required: Health Endpoint

Diosc monitors MCP server health. Implement a /health endpoint:

app.get('/health', (req, res) => {
  // Check your dependencies
  const healthy = checkDatabase() && checkExternalApis();

  if (healthy) {
    res.status(200).json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      version: '1.0.0'
    });
  } else {
    res.status(503).json({
      status: 'unhealthy',
      timestamp: new Date().toISOString(),
      error: 'Database connection failed'
    });
  }
});

Health Check Behavior

• Diosc calls /health periodically (configurable, default 30s)
• If unhealthy, Diosc stops routing requests to this server
• When healthy again, Diosc resumes routing

Required: Authentication Forwarding

This is the most important Diosc extension. Your MCP server must:

1. Accept auth headers from Diosc
2. Forward them to your APIs
3. Never validate them yourself

Headers Diosc Sends

POST /messages HTTP/1.1
Authorization: Bearer <user's token>
X-User-Auth-Authorization: Bearer <user's token>
X-User-Id: user_123
X-Tenant-Id: tenant_abc
X-Request-Id: req_xyz

How to Handle

async function handleToolCall(toolName: string, args: any, authHeaders: Record<string, string>) {
  // Forward auth to your API
  const response = await fetch(`https://api.example.com/${toolName}`, {
    method: 'POST',
    headers: {
      ...authHeaders,  // Forward all auth headers
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(args)
  });

  return response.json();
}

DO NOT Validate Tokens

// ❌ WRONG - Don't validate in MCP server
if (!validateJwt(authHeaders.Authorization)) {
  throw new Error('Invalid token');
}

// ✅ CORRECT - Just forward, let your API validate
const response = await fetch(apiUrl, { headers: authHeaders });
// Your API will return 401 if token is invalid

See Authentication for detailed patterns.

Recommended: Connection Pooling Support

Diosc pools connections to MCP servers. Your server should:

Handle Multiple Sessions

// Use session IDs to track state
const sessions = new Map<string, SessionState>();

// Don't assume single-client behavior
// Multiple users may connect simultaneously

Graceful Shutdown

process.on('SIGTERM', async () => {
  // Stop accepting new connections
  server.close();

  // Wait for existing requests to complete
  await Promise.all(
    Array.from(sessions.values()).map(s => s.cleanup())
  );

  process.exit(0);
});

Connection Limits

const MAX_CONNECTIONS = 100;

app.get('/sse', (req, res) => {
  if (sessions.size >= MAX_CONNECTIONS) {
    return res.status(503).json({
      error: 'Too many connections'
    });
  }
  // ... handle connection
});

Recommended: Tool Metadata

Add Diosc-specific metadata to tools:

{
  name: "delete_order",
  description: "Permanently delete an order",
  inputSchema: { ... },

  // Diosc extensions
  metadata: {
    // Hint that this is destructive
    dangerous: true,

    // Suggest approval requirement
    requiresApproval: true,

    // Category for organization
    category: "orders",

    // Rate limit hint
    rateLimit: "10/minute"
  }
}

Diosc uses this metadata for:

• Approval policy matching
• UI categorization
• Rate limiting decisions

Configuration in Admin Portal

After building your MCP server, register it in Diosc:

1. Go to Admin Portal → MCP Servers
2. Click Add MCP Server
3. Configure:

Name: Orders API
URL: https://mcp.example.com/sse
Transport: SSE (default)

4. Test connection
5. Enable for assistants

See Admin Portal: MCP Servers for details.

Checklist

Before deploying your MCP server:

• SSE endpoint at /sse
• Message handling at /messages
• Health check at /health
• Auth headers forwarded (not validated)
• Multiple sessions supported
• Graceful shutdown implemented
• Error responses follow MCP format
• Tools have good descriptions

Next Steps

• Authentication - Detailed auth handling patterns
• Building Tools - Designing effective tools
• Testing - Validating your server