Lingshu Gate

A self-hosted MCP gateway and control plane with explicit identity, tool-access, credential, audit and project-delivery boundaries.

简体中文 · Documentation · Security · Contributing

Use Gate to manage multiple MCP servers, give remote MCP clients controlled tool access, and deliver projects on trusted native hosts. One MCP Gateway, Web Console and control API connect service operations with user governance.

0.4.5 source: the Console opens at /, with compatible old /console links and JSON service discovery. This version consolidates explicit MCP groups, connection-bound instance sessions, per-client on-demand tools, OAuth catalog/editor improvements, account-menu recovery, classification change explanations and verified packaging fixes. Built-in OAuth and its separate management resource remain opt-in.

Groups reference existing instances without copying credentials or granting access. The on-demand directory exposes six bounded discovery/session entries when the client explicitly selects /mcp?tool_mode=on_demand; invocation rechecks real tool and instance authority. Private OAuth selection uses bounded pages, preserves drafts and reconciles unknown write outcomes before a new confirmation. See the release summary and 0.4.5 validation record.

The separate, default-off /mcp/manage resource retains explicit client resources, scopes, consented tools and exact create/update targets. Live owner-confirmed tool changes stay within existing token/family scope ceilings; client tool-cache refresh is a separate operation. Sign-in and Console show the running backend version from /healthz.

The optional Native/Linux rootless Podman executor defaults to disabled and requires separately reviewed host provisioning/readiness. Its Git/proxy/tool preparation and supported offline install/build paths have synthetic regression evidence; real Podman host, ChatGPT OAuth client and multi-machine acceptance remain incomplete. Core remains gateway-only. Source/fixture checks and local candidate packages do not establish formal publication or those external integrations.

Features

Integration validation records earlier exact source checkpoints, synthetic 50,000-tool measurements, native worker evidence and untested boundaries. The 0.4.5 record keeps new candidate checks and packages separate from those historical results.

See the documentation index below for all workflows. Invocation content recording · Git executor decision

Related MCP server: Peta Core

Console screenshots

Captured separately in each language from the 0.4.0 candidate code on an isolated local test instance with synthetic users, services and projects. No real external account, user proxy or production credential is present. Git blockage and disabled OAuth are shown as observed. Screenshots are UI evidence, not production integration acceptance. Capture and validation record.

Overview and invocation statistics · synthetic test instance

MCP tool catalog and effective access · synthetic test instance

Tool classification review and publication · synthetic test instance

Personal MCP workspace · synthetic test instance

Trusted ZIP delivery workspace · synthetic test instance

Git source form with the unavailable executor shown · synthetic test instance

System settings: network profiles and dependency sources · synthetic test instance

Built-in OAuth administration, disabled by default · synthetic test instance

Tool debugging and result review · synthetic test instance

Quick start

Docker Compose

Docker Compose is the shortest path to an isolated Gate control plane and HTTP gateway:

mkdir -p runtime/workspace
docker compose up -d --build core
docker compose ps

Open http://127.0.0.1:8000/. On an empty data volume, Gate creates a one-time administrator password in /data/initial-admin-credentials.json:

docker compose exec core sh -c 'cat /data/initial-admin-credentials.json'

Sign in, change the password immediately, and create narrowly scoped users or API tokens. The one-time credentials file is removed after the password is changed.

The default Compose service binds to 127.0.0.1, runs as UID/GID 10001, uses a read-only root filesystem, and keeps authentication enabled. The Core image connects to external Streamable HTTP servers; use a native installation when Gate must launch local stdio processes or execute project builds.

Prebuilt native package

Download the archive for your platform and SHA256SUMS from GitHub Releases, verify the archive, extract it, then run:

./start.sh

On Windows:

.\start.cmd

The launcher creates package-local data, config, and workspace directories. You can also run lingshu-gate (lingshu-gate.exe on Windows) directly when you provide the required paths through LINGSHU_GATE_* environment variables.

From source

Requirements: Python 3.11, 3.12, or 3.13; Node.js 22.12+ (22.x), 24.x, or 26+; npm; and uv.

uv sync --frozen
npm --prefix web ci
npm --prefix web run build
uv run lingshu-gate

Gate listens on 127.0.0.1:8000 by default. Browsers open the Web Console at /, OpenAPI documentation at /docs, and readiness probe at /readyz. Service information is always JSON at /v1/meta; / also retains JSON for default curl/programmatic requests and explicit acceptable application/json. Old /console bookmarks redirect to / with their query and hash navigation preserved. The independent OAuth entry remains /oauth/consent.

The Roles & Permission Types Console page separates roles and resource permission types into tabs. Search and source/status/level filters keep the lists compact; row actions stay visible and a detail panel shows the full permission set. Copy creates a new custom item with a new code. System-item restrictions and assigned-role/referenced-type deletion checks remain enforced by the API.

First server

Create a vendor-neutral manifest in the configured mcp.d directory or use the Console. An external Streamable HTTP server looks like this:

id: example-http
name: Example HTTP server
enabled: true
launch:
  type: external
transport:
  type: streamable_http
  endpoint: https://service.example/mcp
  protocol_version: "2026-07-28"
auto_start: false

Set protocol_version to auto or a supported explicit version; omission starts with 2026-07-28. HTTP and stdio support different compatibility ranges; see protocol negotiation.

Validate and save the manifest, inspect discovered tools, classify them as read or write, review the result, and publish only the classifications that should be callable. Access is the intersection of control permission, resource grant, published classification, and API-token scope.

For local stdio configuration, credential references, lifecycle behavior, and gateway requests, see MCP gateway and downstream servers.

Project delivery and remote access

Upload, preflight, build, deploy, overwrite, start, cancel and abandon keep their own permissions and confirmations; MCP writes also bind idempotency keys and digests. The Console saves encrypted private drafts, previews deployment differences and supports explicitly requested manual rollback when a protected snapshot is available. See Project delivery, Console delivery and the bundled Delivery Skill.

Remote access can use Gate API tokens, built-in OAuth or an external RS256 IdP; OAuth defaults to disabled. Built-in mode reuses Gate users with separate public sign-in and tool consent; external mode verifies provider-issued tokens. direct HTTPS and secure_mcp_tunnel are operator-managed network choices. A reverse proxy cannot cross NAT alone, and a machine tunnel key is not a user identity. See Built-in OAuth and external identity/network access. Keep Console and /v1 private; expose only the selected mode's MCP, discovery and required /oauth paths.

Security defaults

• Authentication is enabled, and initial credentials are random and local to the data directory.

• Network binding defaults to loopback; remote access belongs behind an HTTPS reverse proxy.

• Session cookies are HttpOnly and SameSite=Lax; enable LINGSHU_GATE_AUTH_COOKIE_SECURE=true behind HTTPS.

• MCP payload logging is disabled by default.

• Secrets are encrypted at rest and returned only as masked metadata; manifests should use ${credential:<id>} references.

• Tool annotations are hints. Human-reviewed, published classifications and explicit grants determine effective access.

• The Docker Core service drops Linux capabilities, prevents privilege escalation, and mounts the workspace read-only.

Read SECURITY.md before exposing Gate outside a single trusted host.

Release downloads

Release automation builds the following archives:

Tagged releases also provide offline Linux Core images for amd64 and arm64 plus an application SPDX SBOM. Every native archive contains SBOM.spdx.json, BUILD-INFO.json, LICENSE, NOTICE, THIRD_PARTY_NOTICES.md, and this README. Verify the selected archive against SHA256SUMS before extraction; see Release artifacts.

Support matrix

Native archives bundle Gate, not every project runtime. Downstream launch and build portability still depends on the project's own toolchain, commands, paths, and dependencies; preflight reports missing requirements before execution.

Support boundaries

• Inbound /mcp is stateless JSON. It does not expose GET/SSE, separate legacy HTTP+SSE, general resources/prompts or unsolicited server messages. Downstream POST SSE responses do not expand inbound support.

• SQLite and quotas have a single-Core/single-process boundary, with no multi-tenancy or distributed quota guarantee. Core cannot execute local build/deploy/start and has no engine socket. Native trusted-project execution is not code isolation.

• Git SSH, automatic hooks/submodules/LFS and redirect credential forwarding are unsupported. Delivery proxies do not flow into runtime MCP or alter global Git/npm settings. Exact manager startup requires an administrator-reviewed Node/CLI registry; tools are not installed automatically.

• Automated checks use synthetic isolated environments. Real ChatGPT/OAuth, user Git/proxy and production upgrade acceptance remain separate. Platform packages and images are available only when the tagged release workflow actually publishes them.

Documentation

• MCP gateway, protocols, tool grants and file references

• Accounts, configuration, credentials and runtime policy

• Built-in OAuth administration and consent

• External identity and remote network access

• Project delivery API/tools and Delivery Skill

• Console delivery, private drafts and rollback

• Git plans, network profiles and dependency sources

• Git executor implementation and rollout decision

• Service operations, debugging, audit and diagnostics

• Invocation input/output recording

• Retention policy and confirmed cleanup

• Deployment, backup, upgrades and recovery

• Release packages, checksums and SBOM

• Architecture and security boundaries

• Development, API and automated checks

• Synthetic browser regression scenarios

• Bounded performance measurement

• UI and accessibility acceptance contract

• 0.4.0 validation and screenshot provenance

License

Lingshu Gate is distributed under the Apache License 2.0. See LICENSE and NOTICE. Third-party components remain subject to their respective licenses; packaged notices are recorded in THIRD_PARTY_NOTICES.md.