Architecture navigation+

Architecture · MCP

The three MCP primitives

The Model Context Protocol exposes server capabilities to a host model through three orthogonal primitives — Tools, Resources, and Prompts. Cognitive Server implements all three under a single sovereign perimeter, so that any reasoning step a host model performs is inspectable, policy-bound, and traceable to its evidentiary source.

Architecture · Stack

The Cognitive Stack

Ten blocks, one hundred phases, from metal to model.

The Cognitive StackTHE COGNITIVE STACK · 10 BLOCKS · 100 PHASES · FROM METAL TO MODELNETWORKJNetwork SovereigntyWireGuard VPN · Traefik TLS · GAIA-X / Pontus-X federation91—100OPSIAuto-configurationAI self-config · system discovery · health rebalancing84—90INTERFACEHFrontend & RBACReact dashboard · 3D RBAC · admin panel76—83ACTIONSGSkills & ArtefactsCatalog of skills v1.0 · Word/Excel/PDF generators66—75PROTOCOLFMCP ServerProprietary MCP host · primitives · tool budgets56—65AUTOMATIONEOrchestration & Ingestn8n · Odoo · Teams · WhatsApp · OCR pipeline46—55STORAGEDPersistencePostgreSQL uuid v7 · Qdrant vector · Redis · encrypted backup36—45COGNITIONCAI Stack LocalOllama · Llama 3 · Mistral · Nomic embeddings · model router26—35COMPUTEBGPU & Container RuntimeNVIDIA / CUDA · Docker · persistent logging16—25METALAHardware BaseDell / HPE / Lenovo / xFusion appliance · TPM 2.0 · Ubuntu 24.04 LTS · hardening1—15BUILT BOTTOM-UP

FIG. 02 · THE COGNITIVE STACK

PRIM-01

MCP

Tools

Invocable actions

  • audit_cloud_config()
  • get_access_logs()
  • verify_training_records()

PRIM-02

MCP

Resources

Read-only context

  • vault://policy/*
  • vault://regulation/*
  • vault://evidence/*

PRIM-03

MCP

Prompts

Templated workflows

  • nis2_incident_triage
  • dora_resilience_check
  • ai_act_conformity

Architecture · Fundamentals

Host, Client, Server

In MCP, the system splits into three roles. The Host is the application running the language model (in Cognitive Server: Core). The Client is the module that opens and manages MCP sessions inside the Host. The Server exposes the capabilities: Tools, Resources and Prompts.

Cognitive Server acts simultaneously as a Host (Core chat) and as a Server (Nexus, Vault, Hub). This distinction is critical to understand the permission model: the Host decides which Servers the Client may contact, and the Server decides what each scope may execute.

Note · Role mappingIn Cognitive Server, Core is the MCP Host. Nexus, Vault and Hub are MCP Servers. Bridge is the transport. Shield is the policy enforcer at the host↔server boundary.

Tools — invocable actions

A Tool is a side-effecting action exposed by the server. The host model may request its invocation; the server is the sole authority on whether the call is permitted and how it is logged. Tools are the only primitive that may mutate state outside the model context.

Each tool ships a JSON Schema describing its parameters, a deterministic name, and a server-side policy binding. On Cognitive Server, every tool call is signed by the tenant JWT, evaluated against the active scope set, and appended to the Chain fabric ledger before execution.

// src/lib/mcp/tools/audit-cloud-config.ts
import { defineTool } from "mcp-tanstack-start";
import { z } from "zod";

export const auditCloudConfig = defineTool({
  name: "audit_cloud_config",
  description: "Audit a cloud configuration against NIS2 controls.",
  parameters: z.object({
    tenant: z.string(),
    regime: z.enum(["NIS2", "DORA", "AI_ACT"]),
  }),
  execute: async ({ tenant, regime }, { auth }) => {
    await requireScope(auth, "audit:read");
    return runAudit(tenant, regime);
  },
});
Note · Server authorityThe host model never executes a tool directly. It emits a JSON-RPC request; the server validates scope, tenant, and policy, then returns the result alongside an audit-chain identifier.

Resources — read-only context

A Resource is a read-only handle to context the host model may consume — configuration files, regulatory texts, internal documentation, retrieval fragments. Resources are addressable by URI and may carry MIME types, versions, and lineage metadata.

On Cognitive Server, every resource fetch is mediated by the VAULT app: data residency is enforced before the bytes leave storage, and the read is recorded for downstream compliance evidence.

server.resource({
  uri: "vault://tenant/{tenantId}/policy/{name}",
  mimeType: "application/json",
  description: "Tenant-scoped policy document, lineage-tracked.",
  read: async ({ tenantId, name }, { auth }) => {
    await requireScope(auth, "vault:read");
    return vault.read(tenantId, name);
  },
});
Spec · MCP 2025-06-18Resources are immutable from the host's perspective. Server-side mutation is the responsibility of a Tool, never a Resource handler — this separation keeps replay deterministic.

Prompts — templated workflows

A Prompt is a server-defined, parameterised workflow that the host can instantiate on behalf of a user. Prompts are how operators encode repeatable reasoning patterns — incident triage, conformity assessment, vendor due diligence — without baking them into the model weights.

Cognitive Server's NEXUS app ships dozens of regulator-aligned prompts out of the box. Each is versioned, signed by the Shield fabric, and replayable: an auditor can re-execute the exact prompt against the exact inputs months later.

server.prompt({
  name: "nis2_incident_triage",
  description: "Classify and route a suspected NIS2 incident.",
  arguments: [
    { name: "signal", required: true },
    { name: "jurisdiction", required: true },
  ],
  build: ({ signal, jurisdiction }) => ({
    messages: [
      { role: "system", content: policyFor(jurisdiction) },
      { role: "user",   content: signal },
    ],
  }),
});

Architecture · Transport

JSON-RPC 2.0 transport

Cognitive Server transmits every MCP message over JSON-RPC 2.0 (Streamable HTTP transport, spec 2025-06-18). Each message carries: jsonrpc: "2.0", method (the primitive name: tools/call, resources/read, prompts/get), params (payload signed with the tenant JWT), and id (request correlation).

The transport is stateless per-request. Streaming sessions use Server-Sent Events over HTTPS with the header Authorization: Bearer {tenant_jwt}. Bridge manages the connection pool and guarantees that no message crosses the tenant perimeter without the correct JWT.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "audit_cloud_config",
    "arguments": { "tenant": "acme-bank", "regime": "DORA" }
  },
  "id": "req_01J8..."
}
Note · PerimeterBridge never exposes raw JSON-RPC to external networks. All traffic is WireGuard-tunneled and TLS-terminated inside the operator perimeter.

Architecture · Deployment

Local vs remote MCP servers

Cognitive Server operates in local-only mode by design. All MCP Servers (Nexus, Vault, Hub) run on the same appliance as the Host (Core). There is no "remote server" mode that points outside the operator perimeter.

This is an architectural decision, not a configuration: the threat model assumes any MCP Server outside the physical perimeter is an unauthorized egress vector. Bridge has no outbound routes configured by default and rejects any server URI that is not localhost or the appliance's internal network.

DimensionLocal-only (Cognitive Server)Remote-capable (others)
Latency<5ms (LAN)>100ms (WAN)
Data egressZero by designConfigurable (risk)
AuditabilityLocal ChainDepends on provider
GDPR complianceGuaranteedContractual
Note · Unsupported by designRemote MCP servers are explicitly unsupported in Cognitive Server. If your use case requires federation across perimeters, see the GAIA-X section in the Architecture Stack.

Architecture · Flow

End-to-end reasoning flow

Operator question to auditable answer in ~1.2s with zero egress.

End-to-end reasoning flowEND-TO-END REASONING FLOW · OPERATOR QUESTION → AUDITABLE ANSWER01Operator
Natural language question via Core chat
02Core
LLM parses intent + verifies SSO session
03Shield
Validates JWT scope + Tenant-ID signature
04Nexus
Selects MCP tools from approved catalog
05Vault + Hub
Reads resources + executes tools
06Core
LLM synthesises response with citations
Every step emits a trace event consumed by Chain07Chain
Trace ID recorded + immutable evidence
Average latency end-to-end: ~1.2 s · GPU inference local · zero egress from the perimeter

FIG. 03 · END-TO-END REASONING FLOW

Architecture · The Fabric

The Fabric

Three cross-cutting layers that bind the four apps into one auditable system.

The Fabric · FAB-01

Shield — Identity & policy enforcement

Shield is the identity and policy layer of Cognitive Server. It implements OAuth 2.1 + OIDC with mandatory PKCE. Every request crossing the perimeter carries a JWT signed by Shield that includes the tenant_id, the active scope set, and a unique jti (anti-replay). Shield evaluates policy before the request reaches any component — no Tool, Resource or Prompt executes without a valid JWT and the correct scope. See /architecture/permissions for the full scope specification.

The Fabric · FAB-02

Bridge — Protocol transport

Bridge manages JSON-RPC 2.0 transport between the Host (Core), the Servers (Nexus, Vault, Hub) and external systems (ERP, CRM, MES). It operates as a tenant-aware proxy-router: the JWT in the authorization header determines routing; Bridge cannot read payloads in clear text. All Bridge traffic is WireGuard-tunneled inside the operator perimeter. No egress routes exist by default.

The Fabric · FAB-03

Chain — Tamper-evident audit ledger

Chain records every reasoning step as a signed, immutable event. Each event carries: trace_id (UUID v7), tenant_id, timestamp_ns, the SHA-256 hash of the input, the SHA-256 hash of the output, and the tenant JWT signature. Events are append-only: no delete endpoint exists. The Chain is exportable as signed JSONL for ECB/EBA inspectors, ISO 27001 auditors and AI supervisory authorities under the EU AI Act. See /compliance for the evidence mapping.

Composing the three

A real workload uses all three. A NEXUS Prompt loads a regulatory Resource from VAULT, calls an audit Tool exposed by HUB, and returns a structured finding. The composition is the unit CORE reasons over — and the unit the Chain fabric records as a single replayable transaction.

Specification references

Cognitive Server tracks the MCP 2025-06-18 Streamable HTTP transport. Multi-tenant routing rides on top of standard JSON-RPC 2.0 with a tenant-scoped JWT in the Authorization header. See the multi-tenant chapter for the isolation contract.