MCP

MCP Gateway is "the external-agent door." That sentence does a lot of work. Without this module, every external agent (Claude Code on a Member's laptop, Cursor on an engineer's IDE, Codex in CI) would need 22 separate OAuth flows + 22 separate discovery loops + 22 separate audit emissions. The naive design — "one MCP server per module, agents figure it out" — is intractable past 3 modules. MCP Gateway collapses 22 to 1 at the edge while keeping per-module ownership intact behind the federation.

MCP Gateway in the runtime — federation map

Auto vs human-in-loop operations matrix

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.

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

An external agent never knows it's talking to 22 modules. From the agent's perspective, https://mcp.cyberos.com is one MCP server with ~80 tools at P0 (~300+ at P3). The federation is at the edge — per-module servers (cyberos.brain, cyberos.skill, etc.) stay separate inside the cluster, but the gateway is the only thing external clients reach. This section locks the federation contract.

SEP-986 naming convention (per-module ownership preserved)

Per-module server registration flow

External client compatibility matrix

The threat model is precise: an external agent (running in Claude Code on a Member's laptop) carries an OAuth token; the agent is fundamentally untrusted (the user might have approved a malicious tool, the agent process might be compromised, the prompt might be injected). The capability broker is the protocol-level guarantee that even a fully-compromised agent cannot escape the bounds of the user's authorised scope.

Tool annotations — what drives gating

Audience-bound OAuth — the broker's auth contract

{
  "iss": "https://auth.cyberos.io/<tenant>",
  "sub": "user:stephen@cyberskill.world",
  "aud": "mcp.cyberos.com",          // ← audience-bound: this token is ONLY valid at MCP Gateway
  "iat": 1763112131,
  "exp": 1763115731,
  "tenant_id": "org:cyberskill",
  "agent_persona": "claude-code@user-stephen",  // ← which external agent is calling
  "scope_grants": [
    {"resource": "brain", "actions": ["read", "write"], "sync_class_max": "shareable"},
    {"resource": "proj",  "actions": ["read", "write"], "engagements": ["acme-q3"]},
    {"resource": "kb",    "actions": ["read"]}
  ],
  "client_id": "claude-code-vsce-extension",   // ← which MCP client requested the token
  "code_challenge": "sha256:…",                // ← PKCE binding
  "jti": "01HZK…"
}

Destructive-op confirmation flow (Elicitation example)

// Agent calls a destructive tool
→ {"method": "tools/call", "params": {"name": "cyberos.brain.delete_memory", "arguments": {"path": "…/draft.md", "mode": "purge"}}}

// Gateway intercepts: annotation destructive=true, no confirmation_token in args
← {"method": "elicitation/create", "params": {
    "message": "Are you sure you want to PURGE this memory? This is irreversible.",
    "schema": {"type": "object", "properties": {"confirm": {"type": "boolean"}, "reason": {"type": "string"}}, "required": ["confirm", "reason"]}
  }}

// Agent forwards to user; user responds in client UI
→ {"method": "elicitation/response", "params": {"confirm": true, "reason": "Outdated draft superseded by v2"}}

// Gateway forwards original call with confirmation context
// Audit row records BOTH the elicitation prompt AND the user's response
{"op": "put", "path": "meta/mcp-invocations/…", "extra": {"tool": "cyberos.brain.delete_memory", "elicitation": {"prompt": "…", "user_confirmed": true, "reason": "Outdated draft superseded by v2"}}}

An agent's effectiveness is bounded by what it can discover. MCP Gateway is the registry external agents use to introspect what CyberOS can do: tools/list (verbs), prompts/list (templated workflows), resources/list (readable data paths), and capabilities (which MCP features are supported). This section locks the discovery surface contracts.

Discovery endpoints

Tasks primitive — long-running work

Prompt templates — pre-canned workflows

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