# Unla

> MCP Server

MCP Gateway: Transforms existing APIs into MCP servers with zero code. Dockerized, easy deployment & management.

## Overview

- **Category:** Developer Tools
- **Language:** TypeScript
- **Stars:** 2203
- **Forks:** 105
- **Owner:** AmoyLab
- **GitHub:** https://github.com/AmoyLab/Unla
- **Created:** 2025-04-15T08:51:28+00:00
- **Updated:** 2025-07-07T15:25:19+00:00
- **Source:** https://model-context-protocol.com/servers/unla

## Setup

## Setup

These instructions detail how to get started with Unla using Docker.

### Prerequisites

*   Docker installed and running on your system.

### Installation Steps

1.  **Configure Environment Variables:**

    Before running the Docker container, you need to set the required environment variables.  These variables configure the OpenAI API key, the model to use, a secret key for JWT authentication, and the super administrator credentials.

    ```bash
    export OPENAI_API_KEY="sk-eed837fb0b4a62ee69abc29a983492b7PlsChangeMe"
    export OPENAI_MODEL="gpt-4o-mini"
    export APISERVER_JWT_SECRET_KEY="fec6d38f73d4211318e7c85617f0e333PlsChangeMe"
    export SUPER_ADMIN_USERNAME="admin"
    export SUPER_ADMIN_PASSWORD="297df52fbc321ebf7198d497fe1c9206PlsChangeMe"
    ```

    **Important:** Replace the placeholder values with your actual OpenAI API key, desired model, a strong secret key, and secure administrator credentials.

2.  **Run the Docker Container:**

    Use the following `docker run` command to start the Unla container:

    ```bash
    docker run -d \
      --name unla \
      -p 8080:80 \
      -p 5234:5234 \
      -p 5235:5235 \
      -p 5335:5335 \
      -p 5236:5236 \
      -e ENV=production \
      -e TZ=Asia/Shanghai \
      -e OPENAI_API_KEY=${OPENAI_API_KEY} \
      -e OPENAI_MODEL=${OPENAI_MODEL} \
      -e APISERVER_JWT_SECRET_KEY=${APISERVER_JWT_SECRET_KEY} \
      -e SUPER_ADMIN_USERNAME=${SUPER_ADMIN_USERNAME} \
      -e SUPER_ADMIN_PASSWORD=${SUPER_ADMIN_PASSWORD} \
      --restart unless-stopped \
      ghcr.io/amoylab/unla/allinone:latest
    ```

    **Explanation of parameters:**

    *   `-d`: Runs the container in detached mode (in the background).
    *   `--name unla`: Assigns the name "unla" to the container.
    *   `-p 8080:80`: Maps port 80 on the container to port 8080 on the host machine (for the web interface).
    *   `-p 5234:5234`, `-p 5235:5235`, `-p 5335:5335`, `-p 5236:5236`: Maps other necessary ports.
    *   `-e ENV=production`: Sets the environment to production.
    *   `-e TZ=Asia/Shanghai`: Sets the timezone.  Change this to your local timezone.  A list of valid timezones can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
    *   `-e OPENAI_API_KEY=${OPENAI_API_KEY}`: Passes the OpenAI API key as an environment variable.
    *   `-e OPENAI_MODEL=${OPENAI_MODEL}`: Passes the OpenAI model as an environment variable.
    *   `-e APISERVER_JWT_SECRET_KEY=${APISERVER_JWT_SECRET_KEY}`: Passes the JWT secret key as an environment variable.
    *   `-e SUPER_ADMIN_USERNAME=${SUPER_ADMIN_USERNAME}`: Passes the super admin username as an environment variable.
    *   `-e SUPER_ADMIN_PASSWORD=${SUPER_ADMIN_PASSWORD}`: Passes the super admin password as an environment variable.
    *   `--restart unless-stopped`: Configures the container to restart automatically unless explicitly stopped.
    *   `ghcr.io/amoylab/unla/allinone:latest`: Specifies the Docker image to use.

### Configuration Requirements

*   **Environment Variables:**  The environment variables defined in step 1 are crucial for configuring the Unla instance.  Ensure they are set correctly before running the Docker container.
*   **MCP Server Configuration:** After launching the container, you'll need to configure an MCP Server through the web interface.  A sample configuration is available at: [https://github.com/amoylab/unla/blob/main/configs/proxy-mock-server.yaml](https://github.com/amoylab/unla/blob/main/configs/proxy-mock-server.yaml).

### Access and Initial Configuration

1.  **Access the Web Interface:**

    *   Open `http://localhost:8080/` in your web browser.
    *   Log in using the `SUPER_ADMIN_USERNAME` and `SUPER_ADMIN_PASSWORD` you configured earlier.

2.  **Add an MCP Server:**

    *   Copy the configuration from the example YAML file: [https://github.com/amoylab/unla/blob/main/configs/proxy-mock-server.yaml](https://github.com/amoylab/unla/blob/main/configs/proxy-mock-server.yaml)
    *   In the Unla web interface, click "Add MCP Server."
    *   Paste the configuration and save it.

### Available Endpoints

After configuring an MCP Server, the service will be accessible at the following endpoints:

*   MCP SSE: `http://localhost:5235/mcp/user/sse`
*   MCP SSE Message: `http://localhost:5235/mcp/user/message`
*   MCP Streamable HTTP: `http://localhost:5235/mcp/user/mcp`

Configure your MCP Client to use the `/sse` or `/mcp` suffix URLs.

## Tools

## Available Tools

**Unla** provides a suite of tools and features to seamlessly transform existing APIs and services into MCP-compliant endpoints. Here's a breakdown:

### 🔌 Protocol & Proxy Capabilities

*   **RESTful API to MCP Server Conversion:** Converts existing RESTful APIs into MCP Servers. This allows clients to interact with legacy APIs using the MCP protocol.
    *   *Usage:* Configure Unla with the REST API endpoint and desired MCP mapping in the YAML configuration.
*   **MCP Service Proxying:** Proxies requests between MCP clients and existing MCP servers. This enables Unla to act as a gateway, routing MCP traffic to backend MCP services.
    *   *Usage:* Configure Unla with the target MCP server address in the YAML configuration.
*   **gRPC to MCP Server Conversion (Planned):**  *Future support* for converting gRPC services to MCP Servers.
*   **WebSocket to MCP Server Conversion (Planned):** *Future support* for converting WebSocket services to MCP Servers.
*   **MCP SSE Support:** Supports the MCP Server-Sent Events (SSE) protocol for real-time data streaming.
    *   *Usage:* Clients can subscribe to MCP SSE endpoints to receive updates from the server.
*   **MCP Streamable HTTP Support:** Supports MCP Streamable HTTP for efficient data transfer.
    *   *Usage:* Clients can use HTTP requests to stream data to and from the MCP server.
*   **MCP Response Media Support:** Supports MCP responses including text, images, and audio.
    *   *Usage:* Configure the API to return data in the desired format (text, image, or audio), and Unla will handle the MCP encoding.

### 🧠 Session & Multi-Tenant Support

*   **Persistent Session Support:** Provides persistent and recoverable session management.
    *   *Usage:* Unla maintains session state, allowing clients to resume interrupted sessions.
*   **Multi-Tenant Support:** Supports multiple tenants, allowing different organizations or users to share the same Unla instance.
    *   *Usage:* Configure Unla with tenant-specific settings and access controls.
*   **MCP Server Grouping & Aggregation (Planned):** *Future support* for grouping and aggregating multiple MCP servers into a single endpoint.

### 🛠 Configuration & Management

*   **Automatic Configuration Fetching & Hot-Reloading:** Automatically fetches configuration updates and applies them without restarting the service.
    *   *Usage:* Unla monitors the configuration source (e.g., file, database) for changes and automatically reloads the configuration.
*   **Configuration Persistence:** Persists configuration data to various storage options (Disk, SQLite, PostgreSQL, MySQL).
    *   *Usage:* Choose the desired storage backend in the Unla configuration file.
*   **Configuration Sync:** Synchronizes configuration across multiple Unla instances via OS Signals, HTTP, or Redis PubSub.
    *   *Usage:* Configure the desired synchronization method in the Unla configuration file.
*   **Configuration Version Control:** Provides version control for configuration changes.
    *   *Usage:* Track and revert to previous configuration versions using the management UI or command-line tools.

### 🔐 Security & Authentication

*   **OAuth-Based Pre-Authentication:** Supports OAuth-based pre-authentication for MCP Servers.
    *   *Usage:* Configure Unla with the OAuth provider details to protect MCP endpoints.

### 🖥 User Interface

*   **Intuitive Management UI:** Provides a web-based interface for managing Unla configurations and monitoring service health.
    *   *Usage:* Access the UI through a web browser to add MCP Servers, modify configurations, and view logs.

### 📦 Deployment & Operations

*   **Multi-Replica Service Support:** Supports deploying multiple Unla instances for high availability and scalability.
    *   *Usage:* Deploy multiple Unla instances behind a load balancer.
*   **Docker Support:** Provides a Docker image for easy deployment and containerization.
    *   *Usage:* Use the `docker run` command to launch Unla in a Docker container.
*   **Kubernetes & Helm Deployment Support:** Supports deployment on Kubernetes using Helm charts.
    *   *Usage:* Use Helm to deploy and manage Unla on a Kubernetes cluster.