Unla MCP Gateway

Author: AmoyLab

Description: A lightweight, highly available MCP gateway that can (1) proxy existing MCP servers and (2) transform existing REST APIs into MCP-compliant endpoints via YAML configuration (zero code changes). Includes a built-in management web UI, supports MCP SSE and Streamable HTTP transports, session persistence, multi-tenant operation, config hot-reload/sync, OAuth-based pre-auth, and Docker/Kubernetes/Helm deployment.

Stars: 2.1k

Forks: 169

License: MIT License

Category: Open Source

GitHub Website Documentation Discord

Overview

Installation

Unla README documents Docker-based deployment.

1) Configure environment variables:

export APISERVER_JWT_SECRET_KEY="changeme-please-generate-a-random-secret"
export SUPER_ADMIN_USERNAME="admin"
export SUPER_ADMIN_PASSWORD="changeme-please-use-a-secure-password"

2) Launch the container:

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 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

3) Access the Web Interface:

- Open: http://localhost:8080/

- Log in with the administrator credentials you configured.

4) Add an MCP Server configuration:

- Copy the example config from: https://github.com/amoylab/unla/blob/main/configs/proxy-mock-server.yaml

- In the web UI, click “Add MCP Server”, paste the configuration, and save.

For the full deployment/configuration guide, see: https://docs.unla.amoylab.com/getting-started/quick-start

FAQs

How do I write a YAML configuration to convert a specific REST API endpoint into an MCP tool using Unla MCP Gateway?

Unla requires defining REST endpoint URL, HTTP method, request parameters, and response mapping in YAML format within the "Add MCP Server" dialog. The YAML specifies JSON-to-MCP tool output transformation, including parameter types, authentication headers, and error handling. Consult the official quick start for schema examples showing field-level mapping syntax and authentication methods.

What are the differences between the SSE and Streamable HTTP transport endpoints in Unla MCP Gateway, and when should I use each one?

The content documents that Unla exposes SSE at port 5235 and Streamable HTTP at port 5236 but doesn't explain their technical differences. Generally, SSE provides unidirectional server-to-client streaming over persistent HTTP connections, while Streamable HTTP supports bidirectional streaming. Choose SSE for simpler client compatibility; use Streamable HTTP when your MCP client requires request-response streaming.

How does Unla MCP Gateway handle session persistence across multiple client connections, and what storage backends does it support?

The content confirms Unla supports session persistence but doesn't specify implementation details or storage backends. Based on its multi-tenant architecture and Docker deployment, session state likely persists in-memory or through external stores like Redis or PostgreSQL. Teams should consult configuration documentation to confirm supported backends before production use.

How do I set up OAuth2 with PKCE authentication on Unla MCP Gateway to secure internet-exposed MCP endpoints?

The content confirms OAuth2 with PKCE support exists in v0.9.2 but doesn't provide configuration steps. You'll need to consult Unla's official deployment documentation or GitHub repo configuration examples for PKCE setup parameters, including client registration, redirect URIs, token endpoints, and scope definitions. Test the OAuth flow in staging with your exact client transport before exposing endpoints externally.

Can Unla MCP Gateway aggregate tools from multiple upstream MCP servers into a single namespace, and how does it handle naming conflicts?

Yes, Unla aggregates multiple upstream MCP servers behind one endpoint. The content confirms consolidation but doesn't document namespace collision behavior. In practice, most MCP gateways prefix tools with server identifiers or use last-registered-wins semantics. Teams should test naming conflicts in staging with overlapping tool names across backends to confirm actual behavior before production deployment.

What are the performance implications of routing all MCP traffic through Unla Gateway compared to connecting clients directly to individual MCP servers?

Routing through Unla adds latency from network hops, serialization overhead, and centralized bottleneck risk under load. However, connection pooling, reduced TLS handshakes, and centralized caching can offset costs. The cited materials lack benchmarks, so test throughput and P95 latency in staging with realistic concurrent client counts before deploying.