Noumena MCP Gateway Poc

努美纳MCP网关

MCP（模型上下文协议）网关，使AI代理和用户能够通过基于Envoy的路由、使用NPL支持的捆绑包的OPA策略评估、JWT身份验证和凭证注入安全地访问上游MCP服务。

建筑

                         ┌──────────────┐
                         │   Keycloak   │
                         │   (OIDC)     │
                         └──────┬───────┘
                                │ public-net
   Agents / Users ──────► ┌─────┴──────┐
   (JWT auth)              │   Envoy    │
                           │  AI Gateway│
                           └──┬──┬──┬───┘
                              │  │  │
                   policy-net │  │  │ backend-net
                              │  │  │
                   ┌──────────┴┐ │  ├──────────────────────┐
                   │   OPA     │ │  │                       │
                   │ Sidecar   │ │  │  supergateway sidecars│
                   │(ext_authz)│ │  │ ┌─────────┐ ┌───────┐│
                   └─────┬─────┘ │  │ │DuckDuck │ │GitHub ││
                         │       │  │ │Go  MCP  │ │ MCP   ││...
                   ┌─────┴─────┐ │  │ └─────────┘ └───────┘│
                   │  Bundle   │ │  └──────────────────────┘
                   │  Server   │ │
                   └─────┬─────┘ │ secrets-net
                         │       │
                   ┌─────┴─────┐ ┌──────┴──────┐
                   │NPL Engine │ │ Credential  │
                   │(PolicyStore)│ │   Proxy     │
                   └───────────┘ └──────┬──────┘
                                 ┌──────┴──────┐
                                 │    Vault    │
                                 │  (secrets)  │
                                 └─────────────┘

四层网络隔离：代理只能访问Envoy和Keycloak（公共网络）。OPA和NPL引擎在政策网络上。保险库和凭证代理位于秘密网络上。后端MCP服务（超级网关侧车）位于后端网络上。

组件

快速开始

先决条件

• Docker&Docker编写
• Node.js 18+（用于MCP检查器）

1.启动堆栈

cd deployments
docker compose up -d

# Wait for all services to be healthy
docker compose ps

2.播种门户

AIGW配置见容器种子AI网关。

这将引导GatewayStore使用服务、工具、访问规则和治理配置。

3.打开仪表板

打开 http://localhost:8888 并使用登录 admin / Welcome123仪表板提供了一个完整的管理界面，用于管理服务目录、访问规则、治理规则、审批和用户。

4.与MCP检查器连接

npx @modelcontextprotocol/inspector

• 运输：流式HTTP
• 统一资源定位符: http://localhost:8000/mcp
• 认证：OAuth（通过内置OAuth代理端点自动执行）
• 网关公开RFC 9728/8414 OAuth发现、重定向 /authorize 到Keycloak和代理 /token --MCP检查器自动处理流程
• 以注册用户身份登录（例如。， jarvis / Welcome123)

访问UI

代理连接

所有端点都需要通过Keycloak进行JWT身份验证。Envoy使用Keycloak的JWKS端点验证令牌。

双边流媒体

网关支持 双向流媒体 通过MCP流式HTTP：

• POST/mcp --代理到服务器：JSON-RPC请求（初始化、工具/列表、工具/调用）
• GET/mcp --服务器到代理：服务器发起的通知的长期SSE流

Envoy通过以下方式路由GET/mcp timeout: 0s （永不超时），因此通知流无限期保持打开状态。JWT身份验证和ext_authz检查在流设置时发生一次。

OPA政策授权

每个MCP请求都通过Envoy的 ext_authz 过滤器，通过gRPC调用OPA。OPA评估注册政策(policies/mcp_authz.rego)使用内存中的捆绑数据——请求路径中的网络I/O为零。

运作原理

NPL PolicyStore ──SSE──► Bundle Server ──bundle──► OPA (in-memory data)

Envoy (port 8000)
  │ ext_authz (gRPC)
  ▼
OPA Sidecar (port 9191 gRPC / 8181 HTTP)
  └─ Layer 1: Rego rules + in-memory bundle data (~11ms avg E2E)
     Zero network I/O. Bundle rebuilt on NPL mutation via SSE push.

策略链中的三个组件：OPA+捆绑服务器+NPL。捆绑服务器将NPL状态桥接到OPA捆绑包中。无轮询，无缓存过期——SSE对每个突变都进行推送。

授权流程

1. Agent → Envoy            POST /mcp: tools/call "duckduckgo.search"
2. Envoy                    Validates JWT (Keycloak JWKS)
3. Envoy → OPA              ext_authz (gRPC): forwards JSON-RPC body + headers
4. OPA                      Decodes JWT: userId=jarvis@acme.com
5. OPA                      Parses JSON-RPC: method=tools/call, tool=duckduckgo.search
6. OPA                      Three-layer evaluation (in-memory bundle data):
                              - Layer 1 (Catalog): service enabled? tool registered?
                              - Layer 2 (Access Rules): caller matches a rule for this service/tool?
                              - Layer 3 (Governance): if tag=logic, in-memory constraints + recipients (+ NPL approval if needed)
7. OPA → Envoy              allow or deny (with X-OPA-Reason header)
8. Envoy → Backend MCP      Routes to supergateway sidecar (if allowed)
9. Backend → Envoy → Agent  SSE response streamed back

政策规则

捆绑传播

• NPL突变 （例如，管理员禁用工具）→ SSE活动→ 捆绑服务器重建→ OPA重新加载
• 传播延迟：近乎即时（SSE推送，而非轮询）
• 没有冷电话：OPA在首次加载包后始终在内存中有数据

网关商店+服务治理（v4）

GatewayStore                    Single protocol, single instance
  ├── Catalog                   Services + tools with acl/logic tags
  ├── Access Rules              Claim-based and identity-based authorization
  └── Revoked Subjects          Emergency kill switch

ServiceGovernance               One instance per governed service
  ├── Tool Configs              Per-tool constraints (regex, in/not_in, max_length)
  ├── Pending Requests          Logic tool calls awaiting approval
  └── Approval Settings         Per-tool approval requirements + deadlines

ApprovedRecipients              Workflow governance for sensitive parameters
  ├── Approved Recipients       Per-tool approved email addresses/domains
  ├── Agent Identity            Caller-specific enforcement (e.g., only AI agents)
  └── Supervisor Approval       Human-in-the-loop recipient approval workflow

捆绑服务器在一次调用中读取GatewayStore(getBundleData())以及来自ServiceGovernance、Approved Recipients和ToolAuthorization实例的治理数据（工具配置、收件人绑定、工具授权）。所有数据都包含在OPA包中，用于内存评估。

对于逻辑标记的工具，OPA评估 三阶段治理检查 完全在记忆中：

1. 第一阶段——限制：检查捆绑包中工具配置的参数级约束（正则表达式，in/not_in，contains，not_contains，max_length）
2. 第2阶段——收件人绑定：检查特定于呼叫者的收件人限制（批准的收件人：域匹配、电子邮件白名单）
3. 第3阶段——审批工作流程：如果 requiresApproval=true，直接调用NPL获取审批状态机（罕见路径，仅网络跳转）

凭证注入

机密（API密钥、令牌）存储在Vault中，并在启动时注入到超级网关容器中。

注入流

1. 管理员将机密存储在Vault中（通过Vault UI或CLI）
2. 超级网关容器启动并调用凭据代理
3. 凭证代理从Vault中提取，返回注入的字段
4. Supergateway将字段导出为环境变量
5. STDIO MCP工具由环境中的凭据生成

两个凭证范围

看 docs/CREDENTIAL_注射.md 了解架构细节。

配置

services.yaml（仅限Bootstrap）

定义上游MCP服务及其工具。用作NPL状态的持久缓存，用于批量导入/导出。 运行时不读取 --OPA从捆绑包服务器构建的捆绑包中加载策略数据。

services:
  - name: "duckduckgo"
    displayName: "DuckDuckGo"
    type: "MCP_STDIO"
    enabled: true
    command: "docker run -i --rm --init mcp/duckduckgo"
    tools:
      - name: "search"
        enabled: true

user_access:
  default_template:
    enabled: false
  users:
    - userId: "jarvis@acme.com"
      keycloakId: "..."
      tools:
        duckduckgo:
          - "*"       # Wildcard: all tools

证书.yaml

将凭据名称映射到Vault路径和注入目标：

mode: simple
tenant: acme

credentials:
  google_gemini:
    vault_path: secret/data/tenants/{tenant}/services/gemini/api
    injection:
      type: env
      mapping:
        api_key: GEMINI_API_KEY

service_defaults:
  gemini: google_gemini

环境变量

捆绑服务器

凭证代理

项目结构

noumena-mcp-gateway/
├── policies/              # OPA Rego policies (ext_authz)
│   ├── mcp_authz.rego     # v4 authorization: three-layer catalog/access/governance
│   └── mcp_authz_test.rego # Rego unit tests (opa test policies/ -v)
│
├── bundle-server/          # OPA bundle server (Python)
│   └── server.py           # Reads NPL GatewayStore, serves OPA bundles, SSE-triggered rebuild
│
├── dashboard/              # Admin web UI (Python + single-page HTML)
│   ├── server.py           # API server: proxies to NPL, Keycloak, OPA, Docker, metrics
│   └── static/index.html   # SPA: catalog, rules, approvals, users, discover, metrics
│
├── credential-proxy/       # Credential injection service (Kotlin/Ktor)
│   └── src/main/kotlin/    # VaultClient, CredentialSelector
│
├── npl/                    # NPL protocol definitions
│   └── src/main/npl-1.0/
│       ├── store/          # GatewayStore (catalog + access rules + revocation)
│       └── governance/     # ServiceGovernance + ApprovedRecipients protocols
│
├── mock-calendar-mcp/      # HTTP-native MCP server (bilateral streaming tests)
│   └── server.js           # Express: POST /mcp + GET /mcp SSE stream
│
├── configs/                # Runtime configuration
│   ├── services.yaml       # Service definitions (bootstrap/cache)
│   └── credentials.yaml    # Credential mappings
│
├── deployments/            # Docker Compose + Envoy config
│   ├── docker-compose.yml  # Full stack with network isolation
│   ├── envoy/
│   │   ├── envoy-config.yaml  # Envoy static config (JWT, ext_authz → OPA, Lua filter, routing)
│   │   └── mcp-servers.json   # aigw-run backend MCP server registry
│   └── docker/
│       ├── Dockerfile.supergateway        # Supergateway sidecar image
│       ├── Dockerfile.dashboard           # Admin dashboard image
│       ├── Dockerfile.credential-proxy
│       └── Dockerfile.mock-calendar       # HTTP-native MCP server image
│
├── keycloak/               # Custom Keycloak image
├── keycloak-provisioning/  # Terraform for Keycloak setup
├── integration-tests/      # Integration test suite (JUnit5: NPL + E2E)
└── docs/                   # Documentation

运行OPA测试

# Install OPA (macOS)
brew install opa

# Run Rego unit tests
opa test policies/ -v

测试

集成测试（JUnit5）

# Requires Docker stack running (docker compose up -d)
cd integration-tests
./gradlew test

测试套件包括：

• NPL测试 （16个测试）：PolicyStore CRUD——注册/启用服务、启用工具、授予/撤销访问、挂起/恢复、上下文路由、getPolicyData
• E2E测试 （11次测试）：通过Envoy的完整管道→ OPA → 后端——初始化、工具/列表、工具/调用允许/拒绝、动态授权撤销管道、暂停服务拒绝

手动验证

# 1. Get a token
TOKEN=$(curl -sf -X POST 'http://localhost:11000/realms/mcpgateway/protocol/openid-connect/token' \
  -d 'grant_type=password&client_id=mcpgateway&username=jarvis&password=Welcome123' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# 2. Call a tool (should 200 if jarvis has access)
curl -X POST 'http://localhost:8000/mcp' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_events","arguments":{"date":"2026-02-14"}}}'

# 3. Inspect OPA bundle data
curl http://localhost:8181/v1/data

文档

许可证

版权所有2025-2026努美纳数字股份公司。保留所有权利。