MCP

Per-module MCP servers create N integration points where every AI agent has to negotiate auth, discover tools, and handle errors. As N grows to 22, the agent's job becomes intractable. The gateway pattern collapses N into 1: agents see a single MCP server with one OAuth flow, one tool catalogue, one discovery endpoint. The 22 modules continue to publish their per-server tools; the gateway federates them. Naming (cyberos.brain.put_memory) preserves the module origin so audit + revocation remain per-module.

The bet: pay the cost of one good federation once. Without MCP Gateway, every agent client (Claude Desktop, Cursor, Cline, custom) has to maintain its own list of N module URLs, N OAuth registrations, N rate-limit handlings. With MCP Gateway, that list collapses to one URL — and replacing a module is a federation-registry update, not a client release.

PRD §8.4 + §9.8 give the full spec. This table is the working summary.

Three layers: an edge that speaks the MCP spec to agents, a federation router that fans tool calls out to per-module gRPC backends, and an audit + observability bridge. The 22 modules each run a per-server (e.g. cyberos.brain) that registers itself with the gateway at startup.

Internal components

The gateway is mostly stateless. Postgres holds the tool registry, Redis caches tool catalogues and Tasks status, BRAIN absorbs the audit rows.

Tool naming convention (SEP-986)

The gateway speaks MCP 2025-11-25 to agents and gRPC to backends. A small admin REST surface lets operators inspect the registry and replay invocations.

MCP surface (canonical)

Backend gRPC surface (per-module servers)

syntax = "proto3";
package cyberos.mcp.backend.v1;

service ModuleMCPServer {
  // Register at gateway startup. Sends manifest of all tools.
  rpc Register(RegisterRequest) returns (RegisterResponse);

  // Tool invocation forwarded from gateway. Streamable response.
  rpc InvokeTool(stream ToolCall) returns (stream ToolResult);

  // For long-running tools the backend returns a task handle.
  rpc TaskStatus(TaskRef) returns (TaskState);

  // Backend may initiate elicitation back through gateway.
  rpc Elicit(ElicitationRequest) returns (ElicitationResponse);

  // Health + drain.
  rpc Health(Empty) returns (HealthResponse);
}

message RegisterRequest {
  string server_id = 1;
  string version = 2;
  repeated ToolDefinition tools = 3;
}

message ToolDefinition {
  string name = 1;                  // "cyberos.brain.put_memory"
  string description = 2;
  string input_schema = 3;          // JSON Schema
  string output_schema = 4;
  string scope_required = 5;
  map<string, string> annotations = 6;
}

message ToolCall {
  string tool_name = 1;
  string args_json = 2;
  string idempotency_key = 3;
  string subject_jwt = 4;
  string persona_version = 5;
  string trace_id = 6;
}

Admin REST surface (operator-only)

Flow 1 — Well-known discovery + tool listing

Flow 2 — Tool invocation with OAuth + RBAC

Flow 3 — Destructive tool with human-confirm gating

Flow 4 — Long-running task via Tasks primitive

Flow 5 — Mid-execution elicitation

A single tool invocation traverses up to nine states. Most calls run synchronously and reach Completed in < 1 s; long-running ones go via the Tasks primitive.

Performance + security NFRs that flow through MCP Gateway. Cross-referenced at nfr-catalog.html#mcp.

Operator CLI cyberos-mcp + ad-hoc mcp-inspector for development.

1. List registered backends

$ cyberos-mcp servers list

SERVER_ID            STATUS    VERSION   TOOLS    LAST_SEEN
cyberos.brain        active    2.0.0     12       2026-05-14T07:21Z
cyberos.skill        active    1.4.0     8        2026-05-14T07:21Z
cyberos.auth         active    0.9.0     7        2026-05-14T07:20Z
cyberos.ai           active    0.8.0     5        2026-05-14T07:21Z
cyberos.crm          draining  0.3.0     11       2026-05-14T07:15Z

2. Inspect a tool

$ cyberos-mcp tool inspect cyberos.brain.delete_memory

name:           cyberos.brain.delete_memory
server:         cyberos.brain
description:    "Delete a memory file (tombstone by default; purge requires DSAR reason)"
scope_required: brain.delete
annotations:
  destructive:     true
  readOnly:        false
  idempotent:      false
  requiresConfirm: true
  openWorld:       false
input_schema:   {path: string, mode: "tombstone"|"purge", reason: string?}

3. Replay an invocation (dry-run, read-only)

$ cyberos-mcp invocations replay --id inv_01HZJ…XK --dry-run

[replay] invocation inv_01HZJ…XK
  tool:       cyberos.brain.search_memory
  agent:      Claude Desktop (claude-desktop-v1.0.45)
  args:       {query: "Singapore HoldCo"}
  original_outcome: ok (12 hits)
  replay_outcome:   ok (12 hits)  — identical
[replay] read-only tool only · audit row NOT written

4. Cancel a stuck task

$ cyberos-mcp tasks cancel --id tsk_01HZJ…XK --reason "client disconnected"

[cancel]  tsk_01HZJ…XK · status: running → cancelled
[backend] cyberos.kb signalled to abort
[audit]   mcp.invocation updated · outcome=cancelled

5. Conformance test

$ cyberos-mcp conformance run

[conformance] MCP 2025-11-25 spec suite · 142 tests
  initialize             ✓ (12 / 12)
  tools/list             ✓ (18 / 18)
  tools/call             ✓ (24 / 24)
  resources/*            ✓ (16 / 16)
  prompts/*              ✓ (14 / 14)
  completion/complete    ✓ (8 / 8)
  tasks/*                ✓ (12 / 12)
  elicitation/*          ✓ (10 / 10)
  sampling/*             ✓ (6 / 6)
  oauth (pkce)           ✓ (14 / 14)
  prm                    ✓ (8 / 8)
[result]   142 / 142 PASSED  · 0 failed · 0 skipped

6. Register a new backend (CTO + CSO approval gate)

$ cyberos-mcp servers register \
    --id cyberos.crm \
    --endpoint grpc://crm.internal:8081 \
    --version 0.3.0 \
    --manifest crm-tools.json \
    --approval-jira CYB-1234

[validate]  manifest: 11 tools · SEP-986 ✓ · annotations ✓
[approve]   CTO ✓  CSO ✓ (per CYB-1234)
[register]  cyberos.crm registered
[catalog]   cache invalidated
[audit]     brain seq=14856