--- type: source-summary title: 'Source: MCP-GATEWAY-ARCHITECTURE.md' modified: 2026-04-07 tags: - mcp-gateway - architecture - ctos-lens - source - preston-test --- # Source: MCP-GATEWAY-ARCHITECTURE.md ## What this source is The **canonical architecture document** for SuiteCentral 2.0's MCP gateway — the control plane that proxies external ERP MCP tools (NetSuite, Business Central) through a governed single entrypoint. Last updated March 21, 2026; status: implemented, feature-flagged rollout. This is the CTO's deepest-technical source in the wiki so far — it names specific TypeScript files, environment variables, policy evaluation rules, JSON-RPC error codes, and OTel span attributes. ## Key claims 1. **Single JSON-RPC entrypoint** for all MCP traffic: **`POST /api/ai/proxy/mcp`** (JSON-RPC 2.0). → [[pages/concepts/suitecentral-2-overview]] 2. **3 base MCP tools (always available)**: - `suitecentral.field_mapping_suggest` - `suitecentral.integration_status` - `suitecentral.governance_check` 3. **2 gateway tools (feature-flagged via `MCP_GATEWAY_ENABLED`)**: - `suitecentral.mcp_discover` — cross-adapter tool discovery - `suitecentral.mcp_call` — cross-adapter tool execution 4. **MCPAggregatorService responsibilities** (the core gateway component): - Adapter registry (NetSuite + Business Central) - Namespaced dispatch: tool calls use prefixes like `netsuite.*` and `bc.*` - Partial discovery when one adapter is unavailable - Governance pre-check + DLP post-scan - Protocol version matrix (handles version mismatches across adapters) 5. **7-step policy evaluation order** (per `MCPPolicyService`): 1. Tenant kill switch check 2. Env denylist match (highest precedence) 3. DB deny match (tenant scoped) 4. Internal `suitecentral.*` default allow 5. DB allow match (tenant scoped) 6. Env allowlist match 7. External default deny This is a deny-by-default policy with multiple override paths. Important for the CTO's "allowlist security" ask on [[pages/concepts/nl-action-gate]]. 6. **Policy Management API** at `/api/mcp/policies` — GET/PUT/DELETE, authenticated, tenant-scoped, admin role required for cross-tenant access. Returns 503 when policy service unavailable. → [[pages/entities/compliance-dashboard]] can link to this. 7. **NetSuite Official MCP Client**: - File: `src/services/netsuite/mcp/NetSuiteOfficialMcpClient.ts` - Uses Oracle's native MCP endpoints: `/services/mcp/v1/all`, optional suiteapp route - **Tool discovery cached with 24-hour TTL** - Circuit breaker + retry strategy - Token invalidation on 401/403 8. **Business Central MCP Client**: - File: `src/services/bc/mcp/BusinessCentralMcpClient.ts` - Supports **static and dynamic modes** - Dynamic mode tool pattern: `bc_actions_search`, `bc_actions_describe`, `bc_actions_invoke` - Logs preview-mode warning during connect (BC MCP is preview-status on Microsoft's side) 9. **6-step security/governance pipeline for `suitecentral.mcp_call`**: 1. Tool-level policy decision (`MCPPolicyService`) 2. Governance input validation (`GovernanceService.validateInput`) 3. Adapter execution 4. DLP scanning/redaction (`DLPService.scanForPII`) 5. Audit event emission (`AuditService`) 6. Cost event recording (`CostTrackingService`, operation: `mcp_proxy`) This is the **complete governance pipeline every external MCP call goes through** — the CTO can verify each step by opening the named source file. 10. **OpenTelemetry instrumentation**: span `mcp.proxy.call` with attributes for tool, system, tenant, policy/governance decisions, latency, and PII summary fields. 11. **JSON-RPC error semantics**: - `-32601`: method/tool not found - `-32602`: invalid params / policy-governance block (this is the code returned when the allowlist blocks a call) - `-32603`: internal processing failure 12. **NetSuite gateway binding requirement**: requires `NETSUITE_MCP_ACCESS_TOKEN`; explicitly documents that client secret values should NOT be used as bearer tokens. Security hardening detail. 13. **Operations checklist (7 steps for rollout)**: 1. Keep `MCP_GATEWAY_ENABLED=false` in baseline 2. Configure allowlist before enabling external tool calls 3. Enable gateway in non-prod, validate `mcp_discover` first 4. Roll out per-user gateway settings via `/api/settings/mcp` 5. Validate DB policy CRUD (`/api/mcp/policies`) before tenant rollout 6. Run `npm run mcp:contract` and `npm run mcp:smoke` 7. Monitor policy-denied and redaction events before broader enablement ## Pages updated by this ingest **Updated** (3 existing pages): - [[pages/concepts/suitecentral-2-overview]] — added the JSON-RPC entrypoint, 3 base + 2 gateway tools, 6-step governance pipeline for mcp_call - [[pages/concepts/nl-action-gate]] — added the allowlist policy evaluation (7-step) which the NL Action Gate's allowlist filtering is part of - [[pages/entities/compliance-dashboard]] — added the Policy Management API (`/api/mcp/policies`) as an additional audit surface ## Notable quotes > "The MCP gateway extends SuiteCentral's MCP server to proxy external ERP MCP tools (NetSuite, Business Central) through a governed control plane." > — Purpose section > "Keep `MCP_GATEWAY_ENABLED=false` in baseline environments." > — Operations checklist item 1 — deny-by-default rollout posture ## Cross-references / contradictions found - **Confirms "middle intelligence layer" framing** from [[sources/ai-governance-layer-video]] — the MCP gateway IS the middle intelligence layer implementation. Architecture detail: single entrypoint, policy before execution, DLP after execution, audit + cost tracking on every call. - **Confirms NL Action Gate's allowlist filtering**: [[sources/narration-scripts]] scene6 mentions "allowlist filtering before service dispatch." This source details the 7-step policy evaluation that implements that filter for external MCP tool calls. The NL Action Gate's own allowlist is presumably similar but scoped to NL-parsed intents rather than MCP tool calls. - **Oracle's MCP endpoints are consumed by SuiteCentral**: `/services/mcp/v1/all` is Oracle's native MCP endpoint (per [[sources/25-competitive-evidence-register]] — Oracle now ships MCP tools free). SuiteCentral's gateway wraps Oracle's MCP tools with governance, turning a free Oracle feature into a SuiteCentral-governed experience. This is the concrete implementation of the "reduces connector moat but not governance moat" framing. - **BC MCP is "preview mode" on Microsoft's side**: the BC client logs a warning on connect. Means Microsoft's Business Central MCP is not yet GA. SuiteCentral supports it anyway, which positions it as early-mover on the BC+MCP axis. - **Feature flags are baseline-disabled**: `MCP_GATEWAY_ENABLED=false` is the default. This is honest: the gateway is *implemented* but is not *on by default*. A customer adopting SuiteCentral 2.0 today gets the 3 base tools; the 2 gateway tools are opt-in per environment. ## Notes - This source is **the architectural CTO validation target**. A CTO who reads the CTO role brief's "what to validate" ask for "failure-path visibility and fallback handling" can open this document, walk the 6-step governance pipeline, open each named source file (`src/services/mcp/MCPPolicyService.ts`, `GovernanceService.validateInput`, `DLPService.scanForPII`, etc.), and verify each step actually exists in code. This is the deepest "trust by looking" affordance in the corpus. - **DI-bound services in `src/inversify/inversify.config.ts`**: the architecture uses Inversify for dependency injection. Adapters are conditionally bound based on environment flags and credentials. This is mature DI architecture, not hand-wiring. - The **cost tracking** step (#6) in the governance pipeline records `operation: 'mcp_proxy'` — meaning the compliance dashboard's "AI Cost Total" metric should distinguish MCP proxy costs from other AI operation costs. First hint at cost taxonomy. - **The 24-hour TTL on NetSuite tool discovery caching** means the gateway doesn't pound NetSuite's MCP endpoint on every request. This is a concrete implementation of the "Governance Pacer" spirit — respecting upstream rate limits by caching.