Skip to main content
Glama
qylhjhd

MCP Security Gateway

by qylhjhd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

MCP Security Gateway（Open-Core）

让企业敢把 AI Agent 接进生产系统的「安全治理网关」——开源核心版。

MCP Client/Agent ──Bearer/JWT──> 网关(策略+审计+代理) ──MCP──> 上游 Server(CRM/工单/知识库)

功能（开源核心 v0.1：M1-M4）

  • MCP 代理：代理上游 tools/list 与 tools/call；stdio 与 Streamable HTTP 双形态服务。

  • 工具级 RBAC + 受限授权：按角色 allow/deny，policy.default: deny 安全默认；allow 规则可携带参数约束（lte/gte/maxLength/pattern/in…），越界 = 约束不满足 = 拒绝；listTools 不泄露无权工具。

  • 身份（M4）：stdio 走 env/静态；HTTP 走 Authorization: Bearer <token>——

    • static：配置文件或 ${ENV} 注入的令牌映射（联调/服务账号）；

    • oidc：JWT + JWKS（issuer/audience 校验），自定义 rolesClaim（支持 Keycloak realm_access.roles 风格点路径）、subjectClaim、agentClaim，可直接对接企业 IdP（企微/飞书/Okta）。

  • 审计哈希链（WORM-lite）：append-only JSONL + SHA-256 前向链；谁-角色-Agent-工具-入参摘要-决策-原因 可完整校验、可检测篡改；进程重启自动续链。

  • YAML 配置（GitOps 友好） + ${ENV_VAR} 替换（令牌不入库）+ CLI。

Related MCP server: SINT Protocol

快速开始

npm install
npm test            # 64 用例：策略/审计链/配置/OIDC 验证/HTTP 与 stdio 端到端
npm run demo        # stdio：Client → 网关 → CRM
npm run demo:http   # HTTP：Bearer viewer/operator 双身份演示（监听 127.0.0.1:8090）
# stdio 模式（作为本地 MCP Server 被 Agent 拉起）
tsx src/index.ts --config examples/gateway.yaml

# HTTP 模式
npm run dev:http
curl -i http://127.0.0.1:8090/mcp            # GET 元数据（可作探针）
# 业务调用请使用任意 MCP Client 并携带 Authorization: Bearer demo-viewer-token / demo-operator-token

examples/gateway.yaml（stdio）与 examples/gateway-http.yaml（HTTP + static 令牌 + OIDC 模板注释）内置演示 CRM 上游：viewer 只读、operator 受限发邮件、delete 全局拒绝。

容器与 K8s（M3）

# 本地/单机（已提供 docker-compose，审计卷持久化）
docker compose up -d --build

# 镜像含：dist 编译产物 + 示例上游；以非 root、只读根文件系统运行
# 审计日志：/app/data/audit.log（哈希链，篡改可检出）

# Kubernetes（deploy/k8s/，按文件名顺序 apply）
kubectl apply -f deploy/k8s/00-namespace.yaml
kubectl apply -f deploy/k8s/10-configmap.yaml
kubectl create secret generic gateway-tokens -n mcp-gateway \
  --from-literal=GATEWAY_TOKEN_VIEWER=$(openssl rand -hex 24) \
  --from-literal=GATEWAY_TOKEN_OPERATOR=$(openssl rand -hex 24)
kubectl apply -f deploy/k8s/30-pvc.yaml -f deploy/k8s/40-deployment.yaml -f deploy/k8s/50-service.yaml

说明：deploy/k8s/20-secret-sample.yaml 仅供开发演示。配置经 ConfigMap 挂载，令牌经 Secret + ${ENV} 注入。镜像构建需在本机或 CI 具备 Docker 的环境执行。

目录结构

src/
├── config/      schema + YAML loader（role 快捷规则、${ENV} 替换、HTTP 认证配置）
├── policy/      engine：纯函数策略评估（deny > 受限 allow > default）
├── audit/       logger：哈希链 JSONL（自动建目录、断链可校验）
├── identity/    Env/静态上下文 + auth.ts：Bearer → IdentityContext（static/OIDC+JWKS）
├── upstream/    MCP Client：stdio / http 适配（协议隔离点）
├── gateway/     Guard：决策 → 审计 → 透传（支持显式会话主体）
├── server/      handlers（共享绑定）+ stdio + http（Streamable HTTP、Bearer 会话）
examples/        示例配置 + CRM Demo Server
deploy/          Dockerfile / docker-compose / k8s manifests
test/            node:test 用例 + stdio/http 演示客户端

开源 / 商业边界

本仓库（开源核心，Apache-2.0）

商业增强版（独立私有仓，专有许可）

MCP 代理（stdio / Streamable HTTP）

行 / 字段级 PII 脱敏

工具级 RBAC + 参数约束

HITL 审批工作台

审计哈希链（WORM-lite）

注册中心 + 供应链扫描

静态 / OIDC 身份接入

合规报告自动导出

YAML 配置 + Docker / K8s 部署件

治理控制台 + 计量与授权

两者仅通过公开契约集成：src/exports.ts 的管道 Hook 契约与审计链只读 API。 开源核不内联任何商业逻辑，也不依赖商业包内部路径。

里程碑状态

  • M1：骨架 + 核心模块（策略 / 审计 / 配置）

  • M2：stdio 代理打通（真实上游 CRM 端到端）

  • M3：Dockerfile 多阶段 + compose + K8s manifests（镜像与 dist 冒烟通过）

  • M4：Streamable HTTP + Bearer 会话 + OIDC / 静态身份验证（12 项新用例）

变更记录见 CHANGELOG.md。

许可与参与

  • 许可：Apache-2.0，见 LICENSE；第三方组件许可见 NOTICE。

  • 贡献：见 CONTRIBUTING.md。

  • 安全问题：请遵循 SECURITY.md，勿开公开 Issue。

Available Tools

2 tools
list_customersB

分页列出客户（只读）

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral disclosure burden and does state the key fact that this operation is read-only. It also signals pagination behavior. It does not mention default page size, return shape, or error behavior, but for a simple read-only list this is a minimal but adequate disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient clause with no filler. Both pagination and read-only are front-loaded and directly useful for tool selection and invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one optional parameter, no nested objects), so the core behavior is mostly covered. However, there is no output schema, no mention of default pagination behavior, and no guidance relative to read_customer, leaving a few practical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description never names or explains the limit parameter. The word '分页' implies pagination, so the agent can guess that limit controls page size, but the meaning is not actually supplied by the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (列出/list), a resource (客户/customers), and adds the pagination and read-only scope. It is distinguishable from the sibling read_customer by plural-vs-singular intent, though it does not explicitly name the sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The paginated-list phrasing implies this tool is for fetching multiple customers, while read_customer likely handles a single record. However, the description gives no explicit when-to-use or exclusion guidance, leaving the agent to infer the boundary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_customerA

读取单个客户详情（只读）

ParametersJSON Schema
NameRequiredDescriptionDefault
customerIdYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explicitly states '只读' (read-only), which is a useful side-effect guarantee, but it does not disclose error behavior, permissions, or what the returned details contain. The core behavioral trait is covered; operational details are not.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. Every word earns its place by stating the action, the target, and the read-only nature.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, read-only tool with no output schema, the description is minimally sufficient: it names the action and the resource. However, it omits any guidance on missing IDs, return shape, and usage boundaries, leaving some context to be inferred.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description never mentions customerId or how to format it. The single parameter is self-explanatory by name, but the description adds no semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('读取') and a specific resource ('单个客户详情'), and explicitly marks the operation as read-only. The word '单个' distinguishes it from the sibling list_customers, so an agent can tell them apart without inspecting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies it is for retrieving one specific customer's details, which contrasts with list_customers, but it never names the sibling or states when not to use it. Guidance is inferred rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedlist_customers
    • First observedread_customer
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: one lists customers in a paginated manner, the other fetches a single customer's details. There is no overlap or ambiguity in their purposes.

Naming Consistency5/5

Both tool names follow the exact same verb_noun pattern: list_customers and read_customer. The naming is perfectly consistent and predictable.

Tool Count3/5

With only two tools, the server feels thin, especially given the name 'Security Gateway' which implies a broader scope. However, the two tools cover a minimal read-only customer lookup workflow, so it is borderline but not extreme.

Completeness3/5

The server provides only read operations (list and get) with no create, update, or delete capabilities. For a customer-focused toolset, this is a notable gap unless the server is intentionally read-only. The mismatch between the server name and the tool domain further obscures expected completeness.

Resources

Related MCP Connectors

Related MCP Servers

  • SentinelGate by Sentinel-Gate

    SentinelGateofficial

    Sentinel-Gate
    A
    license
    Not graded
    quality
    A
    maintenance
    Open-source MCP proxy that enforces security policies, content scanning, and audit logging between AI agents and tool servers
    25
    AGPL 3.0

  • SINT Protocol

    sint-ai
    A
    license
    A
    quality
    A
    maintenance
    Security-enforcing MCP proxy that sits between an AI agent and any number of downstream MCP servers, intercepting every tool call through a capability-token policy gateway that can allow, deny, or escalate to human approval before the call reaches any real tool. It also exposes built-in operator tools for approval workflows, audit trail queries, token management, voice/HUD output, and hierarchical
    21
    13
    Apache 2.0
  • evav-gateway by evavai

    evav-gatewayofficial

    evavai
    A
    license
    Not graded
    quality
    B
    maintenance
    Governed MCP gateway that lets AI agents call tools with policy enforcement, prompt-injection screening, a kill-switch, and tamper-evident signed audit logs.
    Apache 2.0

  • agent-security-gateway

    Un1u6ky
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server that provides a security gateway for AI agents, enforcing allow/confirm/deny policies on tool calls and requiring human approval for risky operations, with full audit logging.
    -