Brain1 — SuiteCentral 2.0 Wiki

Source: MCP-GATEWAY-ARCHITECTURE.md

Ask the notebook for depth →

Last updated

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). → 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 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. → 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):
  14. Keep MCP_GATEWAY_ENABLED=false in baseline
  15. Configure allowlist before enabling external tool calls
  16. Enable gateway in non-prod, validate mcp_discover first
  17. Roll out per-user gateway settings via /api/settings/mcp
  18. Validate DB policy CRUD (/api/mcp/policies) before tenant rollout
  19. Run npm run mcp:contract and npm run mcp:smoke
  20. Monitor policy-denied and redaction events before broader enablement

Pages updated by this ingest

Updated (3 existing pages):

  • suitecentral-2-overview — added the JSON-RPC entrypoint, 3 base + 2 gateway tools, 6-step governance pipeline for mcp_call
  • nl-action-gate — added the allowlist policy evaluation (7-step) which the NL Action Gate’s allowlist filtering is part of
  • 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 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: 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 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.

Graph View

5 min read

💬 Ask the full corpus →

Backlinks