Natoma MCP Gateway

A robust, production-ready gateway that bridges stdio-based MCP clients (like Claude Desktop) with HTTP/SSE-based MCP servers on the Natoma platform.

Overview

The Natoma MCP Gateway acts as a translation layer that enables seamless communication between different MCP (Model Context Protocol) implementations. It operates exclusively in enterprise mode, providing production-grade features including automatic reconnection, health monitoring, and robust error handling.

Features

• Enterprise Gateway: Production-ready gateway with enhanced reliability and monitoring
• Protocol Translation: Converts stdio JSON-RPC messages to HTTP/SSE format and vice versa
• Custom URL Support: Configure custom endpoints for private deployments

Installation

npm install @natomalabs/natoma-mcp-gateway

Usage

Environment Variables

Required environment variables:

• NATOMA_MCP_SERVER_INSTALLATION_ID: Your MCP server installation ID/slug
• NATOMA_MCP_API_KEY: Your Natoma API key for authentication

Optional environment variables:

• NATOMA_MCP_CUSTOM_URL: Custom endpoint URL (overrides default api.natoma.app endpoint)

Corporate Proxy/Firewall Support

If you're running in a corporate environment with tools like ZScaler that perform TLS interception, you may encounter certificate validation errors. You can resolve this using Node.js's built-in support for custom CA certificates:

# Export your corporate CA bundle
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"

# Run the gateway
npx @natomalabs/natoma-mcp-gateway

This approach is the standard Node.js solution for corporate environments.

Command Line Usage

# Run the gateway (--enterprise flag is required)
npx @natomalabs/natoma-mcp-gateway --enterprise

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": [
        "@natomalabs/natoma-mcp-gateway",
        "--enterprise"
      ],
      "env": {
        "NATOMA_MCP_SERVER_INSTALLATION_ID": "your-installation-id",
        "NATOMA_MCP_API_KEY": "your-api-key"
      }
    }
  }
}

For custom endpoint URLs:

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": [
        "@natomalabs/natoma-mcp-gateway",
        "--enterprise"
      ],
      "env": {
        "NATOMA_MCP_SERVER_INSTALLATION_ID": "your-installation-id",
        "NATOMA_MCP_API_KEY": "your-api-key",
        "NATOMA_MCP_CUSTOM_URL": "https://your-custom-endpoint.com/mcp"
      }
    }
  }
}

For corporate environments with custom certificates:

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": [
        "@natomalabs/natoma-mcp-gateway",
        "--enterprise"
      ],
      "env": {
        "NATOMA_MCP_SERVER_INSTALLATION_ID": "your-installation-id",
        "NATOMA_MCP_API_KEY": "your-api-key",
        "NODE_EXTRA_CA_CERTS": "/path/to/corporate-ca-bundle.pem"
      }
    }
  }
}

Architecture

Enterprise Gateway

The gateway operates in enterprise mode with the following features:

• Uses fetch API with enhanced reliability
• Support for both JSON and SSE responses
• Health check monitoring (every 5 minutes)
• Extended timeouts (60 seconds)
• Enhanced error recovery
• Custom endpoint URL support

Protocol Flow

1. Initialization: Gateway connects to Natoma MCP Platform
2. Session Establishment: Secure session created with session ID tracking
3. Message Processing: stdio JSON-RPC messages translated to HTTP/SSE
4. Response Handling: Server responses converted back to stdio format
5. Error Recovery: Automatic reconnection on connection failures

Configuration

The gateway accepts several configuration options through the MCPConfig interface:

• slug: Server installation ID (required)
• apiKey: Authentication API key (required)
• isEnterprise: Must be set to true (mandatory for enterprise mode)
• customUrl: Optional custom endpoint URL (overrides default api.natoma.app)
• maxReconnectAttempts: Maximum reconnection attempts (default: 5)
• reconnectDelay: Delay between reconnection attempts (default: 2000ms)
• timeout: Request timeout (default: 60000ms)

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external systems and data sources. Learn more at modelcontextprotocol.io.

Requirements

• Node.js 18 or higher
• Valid Natoma API credentials
• Network access to api.natoma.app

Development

# Clone the repository
git clone <repository-url>
cd mcp-gateway

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run enterprise mode in development
npm run dev:enterprise

Error Handling

The gateway includes comprehensive error handling:

• Connection Errors: Automatic reconnection with exponential backoff
• Authentication Errors: Clear error messages for invalid API keys
• Timeout Handling: Configurable timeouts with proper cleanup
• Protocol Errors: Validation and error reporting for malformed messages
• Resource Management: Proper cleanup of connections and timeouts

License

MIT

Support

For issues and support, please contact the Natoma team or file an issue in the repository.