npm package: @natomalabs/natoma-mcp-gateway
Description: Natoma MCP Gateway
Latest version: 1.0.5

# 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

```bash
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:

```bash
# 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

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

### Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](https://modelcontextprotocol.io/introduction).

## Requirements

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

## Development

```bash
# 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.