Skip to main content

Overview

@interopio/mcp-http is a TypeScript library that provides HTTP transport implementation for Model Context Protocol (MCP) servers in the io.Intelligence ecosystem. It wraps the MCP Core Server functionality from @interopio/mcp-core with an Express-based HTTP transport layer, exposing MCP capabilities through RESTful HTTP endpoints. The library handles session management for multiple concurrent clients, supports both streaming (Server-Sent Events) and standard JSON response modes, and includes security features like DNS rebinding protection. This HTTP transport makes it possible for AI assistants and other clients to interact with io.Connect Desktop applications, workspaces, and interop methods through the Model Context Protocol over standard HTTP requests.

Key Features​

  • Express-based HTTP Server: Built-in HTTP server with automatic middleware configuration for quick deployment
  • Session Management: Support for multiple concurrent MCP sessions with unique session IDs for handling multiple clients
  • Server-Sent Events (SSE): Streaming responses for real-time communication and long-running operations
  • JSON Response Mode: Optional simple request/response mode without streaming for simpler integrations
  • Resumability: Event store support for reconnection and message resumption across disconnections
  • DNS Rebinding Protection: Security features to prevent DNS rebinding attacks through host and origin validation
  • Flexible CORS: Configurable origin, headers, and exposed headers for cross-origin requests
  • Custom Middleware: Hook for adding custom Express middleware before route registration
  • Multi-Instance Support: Manage multiple MCP server instances per session for complex scenarios

Target Audience​

This library is designed for developers who are:

  • Building HTTP-based MCP servers for io.Connect Desktop or io.Connect Browser
  • Integrating AI assistants with io.Connect applications through the Model Context Protocol
  • Exposing io.Connect functionality (apps, workspaces, interop methods) to external clients over HTTP
  • Developing custom MCP servers that require HTTP transport in the io.Intelligence ecosystem

Installation​

Install the package using npm:

npm install @interopio/mcp-http

Requirements​

Before using @interopio/mcp-http, ensure you have:

  • Node.js 16 or higher: The library requires Node.js version 16 or above
  • TypeScript 4.5 or higher: If using TypeScript, version 4.5+ is required
  • Valid io.Intelligence license key: A signed JWT token license key is required for operation
  • io.Connect instance: Either io.Connect Desktop or io.Connect Browser instance must be initialized

Core Concepts​

HTTP Transport​

The package uses the HTTP transport implementation from @modelcontextprotocol/sdk, exposing three primary endpoints at the /mcp path:

  • GET /mcp: Retrieve messages for an existing session (requires mcp-session-id header). Used for receiving responses and server notifications.
  • POST /mcp: Send messages to the server or initialize a new session. The first POST without a mcp-session-id header initializes a new session.
  • DELETE /mcp: Close a session and clean up associated resources (requires mcp-session-id header).

All endpoints require a mcp-session-id header except for the initial initialization POST request, which returns a new session ID in the response headers.

Session Management​

Each MCP client connection is represented by a session with a unique session ID. Sessions provide isolation between different clients and enable proper resource management.

Out-of-the-Box Configuration:

The package comes with session management fully configured and ready to use. Sessions are automatically created using secure randomUUID() generation with no manual setup required. The default configuration handles session lifecycle, tracking, and cleanup automatically, allowing you to start using the library immediately without additional session configuration.

Session Lifecycle:

  1. Generation: Sessions are automatically created using cryptographically secure randomUUID() by default
  2. Tracking: Each session is stored internally and mapped to its corresponding transport instance
  3. Lifecycle Management: Sessions are created on initialization (first POST request) and closed on DELETE request
  4. Multi-Instance: Each session can manage multiple MCP server instances, allowing clients to work with different server configurations

For advanced use cases requiring custom session ID generation, the sessionIdGenerator configuration option is available in the API reference.

SSE vs JSON Response Modes​

The library supports two response modes to accommodate different client capabilities and use cases:

Server-Sent Events (SSE) - Default​

SSE is the default and recommended mode for most use cases:

  • Streaming: Responses are streamed in real-time as they become available
  • Persistent Connection: Maintains a long-lived connection for efficient communication
  • Long-Running Operations: Better suited for operations that may take time to complete
  • Event-Driven: Supports server-initiated notifications and updates
  • Use When: Building production systems, handling complex interactions, or requiring real-time updates

JSON Response Mode​

JSON mode provides a simpler request/response pattern:

  • Simple Pattern: Standard HTTP request/response without streaming
  • No Persistent Connection: Each request is independent with a discrete response
  • Testing Friendly: Easier to test with standard HTTP tools
  • Limited Features: Does not support server-initiated notifications
  • Use When: Building simple integrations, testing, or when SSE is not supported by the client

Enable JSON mode by setting enableJsonResponse: true in the transport options.

DNS Rebinding Protection​

DNS rebinding attacks can be used to bypass same-origin policies and access local services. This library includes opt-in protection against such attacks:

How It Works:

  • Host Validation: Whitelist specific Host header values that the server will accept
  • Origin Validation: Whitelist specific Origin header values for CORS requests
  • Request Filtering: Reject requests with invalid host or origin headers before processing

Configuration:

DNS rebinding protection is opt-in and requires explicit configuration:

transportOptions: {
  enableDnsRebindingProtection: true,
  allowedHosts: ["localhost:8080", "127.0.0.1:8080"],
  allowedOrigins: ["http://localhost:3000"]
}

When to Enable:

  • Production environments exposed to untrusted networks
  • Servers accessible from web browsers
  • Environments where localhost services need protection from malicious websites

Note: This feature should be carefully configured to balance security and accessibility. Overly restrictive settings may prevent legitimate clients from connecting.

Server-Side Only Implementation​

Unlike @interopio/mcp-web which provides both server and client capabilities, @interopio/mcp-http is intentionally designed as a server-side only package. It does not include client-side functionality for connecting to MCP servers.

Why Server-Side Only:

The @interopio/mcp-http package strictly follows the HTTP transport definition from the MCP Standard specification. By adhering to this standard, the server implementation is guaranteed to be compatible with any MCP HTTP client that follows the same specification. This design approach ensures:

  • Universal Compatibility: Works with any standard-compliant MCP HTTP client
  • Standard Compliance: Follows the official Model Context Protocol HTTP transport specification
  • Focused Implementation: Provides a robust, well-tested server implementation without the complexity of maintaining client code
  • Client Flexibility: Developers can choose any MCP-compliant HTTP client implementation that best fits their needs

If you need client-side functionality to connect to MCP servers from a browser environment, use @interopio/mcp-web instead, which provides both server and client capabilities for web-based scenarios.