Examples

This page provides complete, runnable examples demonstrating different configurations and use cases for @interopio/mcp-http. Each example includes all necessary imports and can be used as a starting point for your implementation.

Basic HTTP Server

A minimal setup that starts an MCP HTTP server on the default port 8080.

import IoIntelMCPHttpFactory from "@interopio/mcp-http";
import IODesktop from "@interopio/desktop";

const desktop = await IODesktop();

await IoIntelMCPHttpFactory(desktop, {
  licenseKey: process.env.IO_LICENSE_KEY!,
});

// Server starts on default port 8080
// Endpoints available at:
// GET http://localhost:8080/mcp - Retrieve messages for an existing session
// POST http://localhost:8080/mcp - Send messages or initialize a new session
// DELETE http://localhost:8080/mcp - Close a session and clean up resources

This example uses all default configurations:

Port: 8080
CORS origin: "*" (all origins allowed)
Response mode: SSE (Server-Sent Events)
Session IDs: Auto-generated using randomUUID()

Custom Port and CORS

Configure a custom port and restrict CORS to specific origins with custom headers.

import IoIntelMCPHttpFactory from "@interopio/mcp-http";
import IODesktop from "@interopio/desktop";

const desktop = await IODesktop();

await IoIntelMCPHttpFactory(desktop, {
  licenseKey: process.env.IO_LICENSE_KEY!,
  server: {
    // Run server on port 9000
    port: 9000,
    // Allow requests from multiple specific origins
    origin: ["https://app.example.com", "https://admin.example.com"],
    // Expose custom headers to clients
    exposedHeaders: ["Mcp-Session-Id", "X-Custom-Header"],
    // Allow additional headers in requests
    allowedHeaders: [
      "Content-Type",
      "mcp-session-id",
      "mcp-protocol-version",
      "Authorization",
    ],
  },
});

This configuration is useful when:

You need to run on a specific port to avoid conflicts
You want to restrict access to known client applications
You need to expose or accept custom headers for authentication or tracking

With DNS Rebinding Protection

Enable security features to prevent DNS rebinding attacks by whitelisting allowed hosts and origins.

import IoIntelMCPHttpFactory from "@interopio/mcp-http";
import IODesktop from "@interopio/desktop";

const desktop = await IODesktop();

await IoIntelMCPHttpFactory(desktop, {
  licenseKey: process.env.IO_LICENSE_KEY!,
  server: {
    port: 8080,
  },
  transportOptions: {
    // Enable DNS rebinding protection
    enableDnsRebindingProtection: true,
    // Whitelist allowed Host header values
    allowedHosts: ["localhost:8080", "127.0.0.1:8080", "mcp-server.local:8080"],
    // Whitelist allowed Origin header values
    allowedOrigins: ["http://localhost:3000", "https://app.example.com"],
  },
});

DNS rebinding protection is recommended when:

Your server is accessible from multiple network interfaces
You need to prevent malicious sites from accessing your local server
Security requirements mandate strict origin and host validation

warning

When DNS rebinding protection is enabled, requests with Host or Origin headers not in the whitelist will be rejected. Ensure all legitimate clients are included in the allowed lists.

Custom Server Configuration

Use the configureServer callback to add custom Express middleware, security features, and additional endpoints.

import IoIntelMCPHttpFactory from "@interopio/mcp-http";
import IODesktop from "@interopio/desktop";
import express from "express";
import helmet from "helmet";
import rateLimit from "express-rate-limit";

const desktop = await IODesktop();

await IoIntelMCPHttpFactory(desktop, {
  licenseKey: process.env.IO_LICENSE_KEY!,
  server: {
    port: 8080,
    configureServer: async (app) => {
      // Add security headers with helmet
      app.use(helmet());

      // Add rate limiting to prevent abuse
      const limiter = rateLimit({
        windowMs: 15 * 60 * 1000, // 15 minutes
        max: 100, // Limit each IP to 100 requests per windowMs
      });
      app.use(limiter);

      // Serve static files from public directory
      app.use(express.static("public"));

      // Add custom health check endpoint
      app.get("/health", (req, res) => {
        res.json({ status: "healthy", timestamp: new Date().toISOString() });
      });

      // Add custom metrics endpoint
      app.get("/metrics", (req, res) => {
        res.json({
          uptime: process.uptime(),
          memory: process.memoryUsage(),
        });
      });
    },
  },
});

The configureServer callback is executed before MCP routes are registered, allowing you to:

Add security middleware like helmet
Implement rate limiting and DDoS protection
Serve static documentation or UI files
Add custom API endpoints for health checks, metrics, or admin functions
Integrate with logging and monitoring systems

Complete io.Connect Desktop Integration

A comprehensive example demonstrating full integration with io.Connect Desktop, including Workspaces API, static and dynamic tools, and working context.

import IoIntelMCPHttpFactory from "@interopio/mcp-http";
import IODesktop from "@interopio/desktop";
import IOWorkspaces from "@interopio/workspaces-api";
import { IoIntelWorkingContextFactory } from "@interopio/working-context";

const desktop = await IODesktop({
  logger: "info",
  libraries: [IOWorkspaces],
});

await IoIntelMCPHttpFactory(desktop, {
  licenseKey: process.env.IO_LICENSE_KEY!,
  server: {
    port: 8989,
    origin: "*",
  },
  transportOptions: {
    // Custom session ID with timestamp and random component
    sessionIdGenerator: () => `mcp-${Date.now()}-${Math.random()}`,
    onsessioninitialized: (sessionId) => {
      console.log(`MCP session ${sessionId} initialized`);
    },
  },
  mcpCoreServer: {
    tools: {
      // Enable system tools for app and workspace management
      system: {
        searchApps: { enabled: true },
        searchWorkspaces: { enabled: true },
        startApps: { enabled: true },
        startWorkspaces: { enabled: true },
      },
      // Define static tools mapped to interop methods
      static: {
        methods: [
          {
            availability: "constant",
            name: "get-portfolio",
            config: {
              description: "Retrieves client portfolio data",
              inputSchema: {
                type: "object",
                properties: {
                  clientId: { type: "string" },
                },
                required: ["clientId"],
              },
              outputSchema: {
                type: "object",
                properties: {
                  portfolio: { type: "object" },
                },
                required: ["portfolio"],
              },
            },
            interop: {
              methodName: "portfolio.get",
              responseTimeoutMs: 5000,
            },
          },
        ],
      },
      // Enable dynamic tool discovery with guard
      dynamic: {
        methods: {
          enabled: true,
          // Only expose interop methods with "mcp_" prefix as tools
          guard: (method) => method.name.startsWith("mcp_"),
        },
      },
    },
  },
  // Integrate working context using the current schema-based API
  mcpWorkingContext: {
    factory: IoIntelWorkingContextFactory,
    config: {
      schema: {
        clientId: {
          type: "string",
          source: {
            context: {
              location: { workspace: { target: "my" } },
              path: "clientId",
            },
          },
        },
      },
    },
  },
});

console.log("MCP HTTP server started successfully");

Application Definition for io.Connect Desktop

To deploy this server as a service application in io.Connect Desktop, create an application definition JSON file:

app-definition.json
[
  {
    "name": "intel-mcp-server",
    "type": "node",
    "details": {
      "path": "%IO_CD_USER_DATA_DIR%/mcp/index.cjs",
      "showConsole": true,
      "passGlueToken": true,
      "logging": true
    },
    "allowLogging": true
  }
]

Application Definition Properties:

Property	Value	Description
`name`	`intel-mcp-server`	Unique application identifier
`type`	`node`	Application type (Node.js service)
`path`	`%IO_CD_USER_DATA_DIR%/mcp/index.cjs`	Path to server entry point using io.Connect Desktop environment variable
`showConsole`	`true`	Display console window for logging
`passGlueToken`	`true`	Pass io.Connect authentication token to the service
`logging`	`true`	Enable io.Connect Desktop logging integration
`allowLogging`	`true`	Allow application to write logs

Place your compiled server code at the specified path (e.g., index.cjs) and register the application definition with io.Connect Desktop. The service will start automatically with the io.Connect Desktop instance.

tip

Use environment variables in the application definition path with the format %VARIABLE_NAME% to reference io.Connect Desktop directories. Common variables include:

%IO_CD_USER_DATA_DIR% - User-specific data directory
%IO_CD_INSTALL_DIR% - io.Connect Desktop installation directory

API Reference - Complete API documentation
MCP Core Documentation - MCP Core configuration

Basic HTTP Server​

Custom Port and CORS​

With DNS Rebinding Protection​

Custom Server Configuration​

Complete io.Connect Desktop Integration​

Application Definition for io.Connect Desktop​

Related Resources​