Lingshu Gate

A self-hosted MCP gateway that connects tools, limits who can call them, and records what happened.

简体中文 · Download 0.5.6 · Get started · Documentation · Security

0.5.0 Console, captured at 2560×1440 with synthetic users and services. Capture record.

Where Gate fits

• One controlled tool entry: connect multiple MCP services, review and publish tools, then give each user or authorization a limited view through one /mcp endpoint.

• Connect existing services: reach private HTTP MCPs through an explicitly configured connector, or expose selected operations from a local OpenAPI snapshot. Use native Gate for trusted local stdio and project delivery.

• Operate with evidence: inspect invocation decisions, constrain effective tool arguments and opt into Prometheus metrics or OTLP traces.

Related MCP server: Peta Core

Quick start

Prebuilt native package

Download the matching OS/CPU archive and SHA256SUMS, verify it, extract it and enter its directory. Run ./start.sh on Linux/macOS or .\start.cmd on Windows. Gate itself needs no host Python, Node.js or Git.

Open http://127.0.0.1:8000/. Read data/initial-admin-credentials.json locally, sign in, change the password and sign in again. The generated initial file is removed and the old session is revoked. The package's own English/Chinese README includes the full platform-specific path.

Released Docker trial

Verify and extract lingshu-gate-v0.5.6-docker-compose.tar.gz, enter that directory and run:

cp .env.quickstart.example .env.quickstart
docker compose --env-file .env.quickstart -f compose.quickstart.yaml up -d --no-build --wait --wait-timeout 120 core
docker compose --env-file .env.quickstart -f compose.quickstart.yaml exec core cat /data/initial-admin-credentials.json

Open http://127.0.0.1:8000/, sign in with those local one-time credentials and change the password. This uses the released image, loopback-only HTTP, authentication, separate trial volumes, UID/GID 10001, a read-only root and no engine socket. PowerShell can use Copy-Item for the first line. See getting started for ports and offline images.

Production deployment

Use the bundle's default compose.yaml and paired DEPLOYMENT.md / DEPLOYMENT.zh-CN.md: select a published digest, prepare readable protected bootstrap credentials, persistent storage and HTTPS with Secure cookies. Follow deployment for exact proxy, origin, backup and upgrade requirements. Keep one Core per database.

From source

Requirements: Git, Python 3.11–3.13, uv, Node.js 22.12+ in 22.x, 24.x or 26+, and npm.

git clone https://github.com/zhigege666/Lingshu-Gate.git
cd Lingshu-Gate
uv sync --frozen
npm --prefix web ci
npm --prefix web run build
uv run lingshu-gate

For a source Docker build, run mkdir -p runtime/workspace and docker compose up -d --build --wait --wait-timeout 120 core from that repository root. Local development explains separate paths, credentials and test commands.

First authorized call

The included demo walkthrough needs no external service account or desktop MCP client. Start the independent in-memory demo, connect it in Gate, review and publish three tools, then create a separate read-only caller. Follow tools/list → gate_catalog_search → gate_tool_describe → gate_tool_invoke using the returned tool reference and revision.

Check the successful audit, deny a write with an unchanged counter, reject an invalid revision, stop/restart the demo and revoke the caller. Gate startup, tool discovery, classification confirmation and publication are separate steps; access still requires both resource grants and token scope.

0.5.6 — HTTP MCP setup and credential management

Connect an external HTTP MCP without hand-writing common authentication headers. Choose None, Bearer Token, API Key, Basic or Custom, select an existing scoped credential or save a new one, then optionally Test connection before saving. The Home shortcut fills the draft and explains its PAT requirements; it never logs in or sends credentials automatically. The 1200 px editor keeps Cancel, Test connection and Save together, with stage-by-stage diagnostics above the actions.

Five gate_http_mcp_* tools cover testing, reviewed configuration plans, application, status and cancellation. Plans support create/update/delete and explicit private-HTTP permission revoke/restore. Five gate_credential_* tools manage encrypted shared credentials with masked reads, revision checks, idempotent writes and dependency-protected deletion. An authorized configuration save includes its exact private-HTTP permission; revoked permission still requires explicit restoration.

Frontend dependencies also include the Vite 8.3.3 and fast-uri 3.1.9 security patches. Old OAuth grants do not gain new tools or scopes. Existing explicitly wildcard-scoped administrator API tokens retain their ceilings. Credential rotation affects subsequent dispatches; testing neither saves a configuration, publishes tools nor verifies every business permission. Back up the database, configuration, encrypted stores and all keys together before upgrading. See HTTP setup and testing, MCP administration, shared credentials, changes and the bilingual release notes.

Architecture overview

flowchart TB
    subgraph Clients["Clients & Tools"]
        AI["AI Coding Agents / LLM Clients"]
        Console["Operator Web Console (/)"]
    end

    subgraph Gate["Lingshu Gate (Control Plane & Gateway)"]
        Gateway["MCP Gateway (/mcp): Full Catalog / On-Demand Discovery"]
        Auth["Authentication & RBAC"]
        Gov["Tool Governance & Classification Review"]
        Delivery["Project Delivery & Build Engine"]
        Audit["Audit, Retention & Content Recording"]
    end

    subgraph Downstream["Downstream MCP Servers"]
        Stdio["Local stdio Processes"]
        HTTP["Streamable HTTP Servers"]
        Container["Managed Container Services"]
    end

    AI --> Gateway
    Console --> Auth
    Console --> Delivery
    Gateway --> Auth
    Gateway --> Gov
    Gateway --> Audit
    Gateway --> Stdio
    Gateway --> HTTP
    Gateway --> Container

Features

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

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.

• Core-managed credentials are encrypted at rest and returned as masked metadata; connector and adapter credentials use separate protected local files. 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 package-specific English/Chinese start pages. Verify the selected archive against SHA256SUMS before extraction; see Release artifacts.

Native and Compose bundles also include paired guides, neutral examples, changelogs, security policies, release notes and the Project Delivery Skill. Start with First authorized call.

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

• Getting started: native, Docker, production and source

• First successful and denied calls

• Tool argument policies

• Private HTTP MCP connector

• Selected OpenAPI operations

• Prometheus metrics and OTLP traces

• MCP gateway, protocols, tool grants and file references

• MCP groups and routing contracts

• On-demand tools discovery

• Accounts, configuration, credentials and runtime policy

• Business accounts and agent-browser bindings

• 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

• Native isolated executor

• 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

• 0.4.7 release candidate validation

Help improve Gate

If Gate solves a problem for you, star the repository to find it again and use GitHub Watch → Custom → Releases for release notifications. Share a minimal, redacted reproduction when reporting an issue, or contribute a small integration example with its permission and failure cases. The first-call guide is a useful starting point for trying the project or showing it to a colleague.

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.