ACR Meta-MCP Forward Proxy & Governance Control Plane

The ACR Meta-MCP Forward Proxy is an enterprise-grade Model Context Protocol (MCP) reverse and forward proxy, sandbox runtime, and dual-consent governance engine. It implements the dual-layer MCP architecture for the Agentic Chat Rooms (ACR) ecosystem: a native/master MCP layer for internal platform orchestration and a governed Meta-MCP fabric for proxying, sandboxing, credential vaulting, and policy-controlling third-party MCP servers (stdio, SSE, Streamable HTTP).

Architecture Overview

                          ┌────────────────────────────────────────────────────────┐
                          │               ACR Native / Master Layer                │
                          │        (Agent Trust Ledger, JetStream Bus, DIDs)       │
                          └───────────────────────────┬────────────────────────────┘
                                                      │ Dual-Consent Gate
┌─────────────────────────────────────────────────────▼─────────────────────────────────────────────────────┐
│                                       ACR Meta-MCP Forward Proxy (Port 20445)                             │
│                                                                                                           │
│  ┌───────────────────────┐   ┌────────────────────────┐   ┌────────────────────────────────────────────┐  │
│  │ Config Ingestion      │   │ Policy Engine          │   │ Auth Vault (SQLite3MultipleCiphers)        │  │
│  │ • Schema Validation   │   │ • Role & Room Scoping  │   │ • AES-256-GCM / ChaCha20-Poly1305 / CBC   │  │
│  │ • Secret Redaction    │   │ • Quarantine Control   │   │ • PBKDF2-HMAC-SHA512 (256,000 iters)       │  │
│  │ • SHA-256 Fingerprint │   │ • Escalation Hooks     │   │ • Multi-Domain Isolation (Personal/Org)    │  │
│  └───────────┬───────────┘   └───────────┬────────────┘   └─────────────────────┬──────────────────────┘  │
│              │                           │                                      │                         │
│              └───────────────────────────┼──────────────────────────────────────┘                         │
│                                          │                                                                │
│                        ┌─────────────────▼──────────────────┐                                             │
│                        │      3-Tier Catalog Projector      │                                             │
│                        │  Raw -> Policy -> Projected View   │                                             │
│                        └─────────────────┬──────────────────┘                                             │
│                                          │                                                                │
│  ┌───────────────────────────────────────▼─────────────────────────────────────────────────────────────┐  │
│  │                                Transport Bridge & Sandbox Execution                                 │  │
│  │  • Stdio Child Process (ToolHive Sandbox: no-network | egress-allowlist | workspace-scoped)          │  │
│  │  • Streamable HTTP JSON-RPC 2.0 Endpoint (POST /mcp)                                                │  │
│  │  • Server-Sent Events (SSE) Multiplexed Tunneling                                                   │  │
│  └─────────────────────────────────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Key Modules & Capabilities

1. Config Ingestion (packages/config-parser)

• Ingests standard mcp_config.json containing stdio (command/args/env) and remote (url/headers) server definitions.
• Automatically redacts inline credentials and tokens into deterministic reference placeholders (sec_ref_<server>_<key>).
• Generates canonical SHA-256 fingerprints for immutable InstallManifest versioning.

2. Multi-Cipher Auth Vault (packages/auth-vault)

• Fuses the cryptographic designs of utelle/SQLite3MultipleCiphers and sqlcipher/sqlcipher.
• Encrypted at rest (vault.db) with 64-byte authenticated magic header ACR_MCDB_V1.
• Supported Ciphers:
  • aes-256-gcm (NIST SP 800-38D AEAD)
  • chacha20-poly1305 (RFC 8439 AEAD)
  • sqlcipher-v4 (AES-256-CBC + HMAC-SHA512 per record)
• Key Derivation: PBKDF2-HMAC-SHA512 (256,000 iterations default) with per-database random salts.
• Domain Boundaries: personal, org, enterprise, ephemeral.
• Master Passphrase Rotation: Atomic re-encryption of all database records.

3. ToolHive-Inspired Sandbox Containment (packages/sandbox-runtime)

• Isolates untrusted stdio processes using 4 containment profiles:
  • no-network: Prohibits external network calls; scrubs proxy settings.
  • egress-allowlist: Allows outbound HTTP/HTTPS exclusively to verified endpoints (e.g. api.github.com, gitee.com).
  • filesystem-readonly: Blocks write operations outside ephemeral runtime /tmp.
  • workspace-scoped: Restricts disk access strictly to designated project directories.
• Host environment variable sanitization and execution timeout bounds.

4. Dual-Consent Policy Engine (packages/policy-engine)

• Enforces access control at both the Master Layer and Meta-MCP Proxy Layer.
• Scopes tool accessibility by caller role (admin, agent, human_operator, guest) and active room deliberation context.
• Instant server quarantine mechanism (toggleQuarantine).
• Human operator confirmation hooks (REQUIRE_HUMAN_CONFIRMATION).

5. 3-Tier Catalog Projector (packages/catalog-projector)

• Raw Catalog: All tools discovered from downstream servers with prefix namespacing (${serverId}__${toolName}).
• Policy Catalog: Tools that pass server health, non-quarantine, and policy permission checks.
• Projected Catalog: Persona-filtered tool view tailored to the requesting agent DID and permissions.

6. Control Plane API & Streamable Gateway (apps/control-plane-api)

• Native HTTP daemon running on port 20445.
• Private Network Access (PNA) and CORS compliant (Access-Control-Allow-Private-Network: true).
• Streamable HTTP JSON-RPC 2.0 gateway at POST /mcp.
• Replay audit logging with sub-millisecond precision.

Environment Variables

| Variable | Default | Description | |---|---|---| | ACR_META_MCP_PORT | 20445 | HTTP listen port for Control Plane and MCP Gateway | | ACR_META_MCP_HOST | 0.0.0.0 | Listen host interface | | ACR_VAULT_PATH | (in-memory) | File path to encrypted MultipleCiphers database (vault.db) | | ACR_VAULT_SECRET | (generated) | Master encryption secret for Auth Vault | | CONTEXT7_API_KEY | (optional) | Dynamic API key for Context7 real-time library docs MCP |

REST API Reference

| Method | Endpoint | Description | |---|---|---| | GET | /health | Daemon status, version, server count, uptime | | GET | /api/v1/meta-mcp/servers | List registered downstream MCP servers | | POST | /api/v1/meta-mcp/servers/import | Import and compile standard mcp_config.json | | POST | /api/v1/meta-mcp/servers/:id/toggle | Enable or disable a registered server | | POST | /api/v1/meta-mcp/servers/:id/quarantine | Toggle quarantine status for a server | | GET | /api/v1/meta-mcp/tools | Query tool catalog (?view=raw\|policy\|projected) | | POST | /api/v1/meta-mcp/tools/call | Invoke a governed tool execution | | GET | /api/v1/meta-mcp/vault/secrets | List vaulted secret refs with domain & cipher info | | POST | /api/v1/meta-mcp/vault/secrets | Store an encrypted secret in the MultipleCiphers DB | | DELETE | /api/v1/meta-mcp/vault/secrets/:refId | Purge a secret from the encrypted DB | | POST | /api/v1/meta-mcp/vault/rotate | Rotate master passphrase & re-encrypt DB | | GET | /api/v1/meta-mcp/audit | Replay cryptographic audit trail logs | | POST | /mcp | Streamable HTTP JSON-RPC 2.0 MCP Gateway |

CLI Usage

Standalone Node CLI (@acr-js/meta-mcp)

# Check daemon health
acr-meta-mcp health

# List registered servers
acr-meta-mcp list

# Import mcp_config.json
acr-meta-mcp import ./path/to/mcp_config.json

# Query tools catalog
acr-meta-mcp tools projected

# Call governed tool
acr-meta-mcp call context7__query-docs '{"libraryId":"/vercel/next.js","query":"App Router"}'

# Manage encrypted Auth Vault
acr-meta-mcp vault list
acr-meta-mcp vault set context7 CONTEXT7_API_KEY "ctx7sk_..." personal chacha20-poly1305
acr-meta-mcp vault rotate "new-secure-passphrase"
acr-meta-mcp vault delete sec_ref_context7_context7_api_key

# Manage and test dynamic port bindings
acr-meta-mcp ports list
acr-meta-mcp ports set acr-meta-mcp 20495
acr-meta-mcp ports test
acr-meta-mcp ports export

# View audit logs
acr-meta-mcp audit

Native Dart CLI (acr-cli)

acr meta-mcp list
acr meta-mcp import ./mcp_config.json
acr meta-mcp tools --view=projected
acr meta-mcp call context7__resolve-library-id '{"libraryName":"React"}'
acr meta-mcp vault list
acr meta-mcp vault set --server=github --key=GITHUB_TOKEN --value="ghp_..."
acr ports list
acr ports set acr-meta-mcp 20495
acr ports test
acr meta-mcp audit

Integration with MCP Clients

Add the ACR Meta-MCP Forward Proxy to any standard MCP client (claude_desktop_config.json, ~/.cursor/mcp.json, etc.):

{
  "mcpServers": {
    "acr-meta-mcp": {
      "url": "http://localhost:20445/mcp"
    }
  }
}

All downstream tools (Context7, GitHub, Gitee, filesystem sandbox, custom agents) will be dynamically projected, sandboxed, and governed under dual-consent policy rules.

Test Suite Execution

npm install
npm test

✔ Meta-MCP Control Plane API & JSON-RPC Gateway (8 tests passed)
✔ Context7 Real MCP Tool E2E Integration & QA Test (7 tests passed)
✔ Auth Vault (SQLite3MultipleCiphers & SQLCipher Engine) (5 tests passed)
✔ Catalog Projector (3-Tier Catalog Pipeline) (2 tests passed)
✔ Config Parser & Manifest Compiler (2 tests passed)
✔ Policy Engine & Dual Consent (3 tests passed)
✔ Registry Core (State Machine & Server Persistence) (1 test passed)
✔ Sandbox Runtime (Containment Engine) (2 tests passed)

30 tests passed, 0 failed (971ms)