MCP Gateway is the tool federation layer that turns CyberOS's 24 modules into a single, coherent MCP server. Each module publishes a per-module server (named cyberos.memory, cyberos.skill, cyberos.crm, ...) that exposes its verbs as tools (memory.update_memory, skill.execute_skill, crm.update_account, ...); the gateway aggregates these into a federated surface that Claude / Codex / Cursor / Cline / any 2025-11-25-spec client sees as one server. OAuth 2.1 + PKCE (RFC 7636) gates every tool call; the audience claim pins the call to a specific module; the RBAC predicate from AUTH enforces who can do what; the persona-version stamp captures which agent authored the call. Tool annotations (destructive / readOnly / idempotent / openWorld) drive human-confirm gating. The Tasks primitive handles long-running work; Elicitation reverses control mid-execution to ask the user a question.

• Strategic role: external-agent door - 24 modules -> one MCP server
• Status: planned - P0, design phase; P0 slice 3
• Spec compliance: MCP 2025-11-25 - Streamable HTTP, Tasks, Elicitation
• External clients (target): Claude, Cursor, Codex, Cline - all 2025-11-25-compliant clients
• Transports: Streamable HTTP, SSE - RFC 9112 chunked + EventSource
• Auth: OAuth 2.1 PKCE - RFC 7636, audience-bound, PRM
• Tools at P0 (est.): ~80 - memory, Skill, AUTH, AI
• Tools at P3 (est.): ~300+ - 24 modules x ~15 verbs each
• Destructive-op gating: human-confirm - via Elicitation or explicit token
• Persona stamp coverage: 100% - on every audit row
• Depends on: AUTH, memory, OBS, plus AI Gateway (P0 slice 1)
• Naming convention: SEP-986 - cyberos.{module}.{verb}_{noun}

The bigger picture - three strategic roles

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 24 separate OAuth flows + 24 separate discovery loops + 24 separate audit emissions. The naive design - "one MCP server per module, agents figure it out" - is intractable past 3 modules. MCP Gateway collapses 24 to 1 at the edge while keeping per-module ownership intact behind the federation.

Role 1 - external-client federation

24 modules -> one MCP server. Claude Code, Cursor, Codex, Cline, and any 2025-11-25-spec client hit a single gateway whose OAuth discovery is served at https://mcp.cyberos.com/.well-known/oauth-protected-resource (RFC 9728, which names the authorization server). The gateway aggregates per-module tool catalogues via SEP-986 naming (cyberos.memory.update_memory, cyberos.proj.create_issue, etc.) so external agents see one server. Per-module servers stay separate behind the edge; federation only happens at the surface. This means Members can use the AI tools they already trust without learning a new orchestrator.

Role 2 - capability broker

Every external invocation gated. Audience-bound OAuth 2.1 + PKCE tokens carry tenant_id + agent_persona + scope_grants per AUTH §2.7. Tool annotations (destructive / readOnly / idempotent / openWorld) drive gating: destructive ops require either an explicit confirmation token in the request or an Elicitation flow that asks the user. The persona stamp on every audit row makes "external agent X did Y" replayable down to which Claude/Cursor session authored it.

Role 3 - tool-discovery surface

The registry external agents introspect. tools/list returns ~80 tools at P0 (~300+ at P3); prompts/list exposes module-specific prompt templates; resources/list exposes memory paths the agent can read. Long-running work (KB ingestion, big migrations, bulk imports) is tracked via the Tasks primitive - the agent can start a task, poll status, get a streaming progress update, and resume on reconnect. Elicitation reverses control mid-execution to ask "should I proceed with the destructive step?".

MCP Gateway in the runtime - federation map

flowchart TB
  subgraph clients["External MCP clients (2025-11-25)"]
    CC["Claude Code"]
    CURSOR["Cursor"]
    CODEX["Codex / GPT-5 agent"]
    CLINE["Cline"]
    OTHER["any compliant agent"]
  end
  MCPGW["MCP Gateway<br/>OAuth 2.1 / Streamable HTTP / Tasks / Elicitation"]
  subgraph perm["Per-module MCP servers (internal)"]
    BRSV["cyberos.memory"]
    SKSV["cyberos.skill"]
    PRSV["cyberos.proj"]
    CRMSV["cyberos.crm"]
    KBSV["cyberos.kb"]
    N["... 19 more"]
  end
  subgraph dep["Platform deps"]
    AUTH["AUTH<br/>scope_grants check"]
    AIGW["AI Gateway<br/>persona stamp resolution"]
    memory["memory<br/>audit chain"]
    OBS["OBS<br/>traces"]
  end
  CC --> MCPGW
  CURSOR --> MCPGW
  CODEX --> MCPGW
  CLINE --> MCPGW
  OTHER --> MCPGW
  MCPGW -. "JWT audience verify" .-> AUTH
  MCPGW -. "fetch persona-version" .-> AIGW
  MCPGW --> BRSV
  MCPGW --> SKSV
  MCPGW --> PRSV
  MCPGW --> CRMSV
  MCPGW --> KBSV
  MCPGW --> N
  MCPGW --> memory
  MCPGW --> OBS
  classDef hub fill:#cffafe,stroke:#0e7490,stroke-width:3px,color:#164e63
  classDef client fill:#e0e7ff,stroke:#3730a3
  classDef internal fill:#f5ede6,stroke:#45210e
  classDef dep fill:#fef6e0,stroke:#9c750a
  class MCPGW hub
  class CC,CURSOR,CODEX,CLINE,OTHER client
  class BRSV,SKSV,PRSV,CRMSV,KBSV,N internal
  class AUTH,AIGW,memory,OBS dep

External clients never reach per-module servers directly. The gateway is the only external surface; this is the protocol-level guarantee that auth + audit + persona-stamp are uniformly applied.

Auto vs human-in-loop operations matrix

Why MCP Gateway exists

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 24, 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 24 modules continue to publish their per-module tools; the gateway federates them. Naming (cyberos.memory.update_memory) preserves the module origin so audit + revocation remain per-module.

• One discovery, all tools. Agents authenticate once via OAuth discovery (/.well-known/oauth-protected-resource, then /.well-known/oauth-authorization-server) and see every module's tools through a single federated tools/list. Per-module servers stay separate; federation is at the edge.
• OAuth-protected, RBAC-evaluated. PKCE-only OAuth 2.1; every tool call audience-bound; every call evaluated by AUTH RBAC; destructive calls human-gated.
• Long-running work, first-class. The Tasks primitive supports operations that exceed the request timeout - the gateway polls the underlying server and reports progress to the caller.

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.

What it does - 5W1H2C5M

This table is the working summary.

External-client federation - 24 modules behind one surface

An external agent never knows it's talking to 24 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.memory, 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)

Tool names follow the cyberos.{module}.{verb}_{noun} SEP-986 convention. The module prefix preserves ownership for audit + revocation; the verb_noun form aligns with MCP convention.

Per-module server registration flow

Each module's MCP server registers itself with the gateway at startup. Registration carries its tool catalogue (with annotations), prompt templates, and resource paths. The gateway maintains a versioned catalogue and pushes list_changed notifications to subscribed clients when modules deploy.

sequenceDiagram
  autonumber
  participant M as cyberos.memory (per-module server)
  participant G as MCP Gateway
  participant DB as Catalogue DB
  participant CL as Subscribed clients (Claude, Cursor)
  participant BR as memory audit
  M->>G: register_module(name, tools[], prompts[], resources[], version)
  G->>DB: upsert module record + tool catalogue
  G->>BR: emit mcp.module_registered audit row
  G->>CL: notification tools/list_changed
  Note over G,CL: subscribed agents re-fetch tools/list
  G-->>M: registered (catalogue_version, registration_token)
  M->>G: heartbeat every 10s (keep-alive)
  Note over G: missed 3 heartbeats -> module marked unhealthy -> tools removed from federation

External client compatibility matrix

The gateway negotiates the highest mutual version at session init. Older clients fall back to SSE transport + bearer-token auth (no PKCE). The older-client tool surface excludes the Tasks and Elicitation features.

Capability broker - every external invocation gated

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": "memory", "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..."
}

The aud claim is the protocol-level guarantee: a token issued for mcp.cyberos.com cannot be replayed against api.cyberos.com. PKCE binding prevents code interception during the auth flow. The scope_grants are checked per tool call against the tool's required resource + action.

Destructive-op confirmation flow (Elicitation example)

// Agent calls a destructive tool
-> {"method": "tools/call", "params": {"name": "cyberos.memory.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 the client UI
-> {"method": "elicitation/response", "params": {"confirm": true, "reason": "Outdated draft superseded by v2"}}

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

Tool-discovery surface - the registry agents introspect

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

For operations that take > 30 s (KB corpus ingestion, memory export, bulk migrations), MCP Gateway returns a Task immediately and lets the agent poll for status. The agent can disconnect and reconnect; the Task persists in Postgres.

Prompt templates - pre-canned workflows

Prompts are MCP-defined templated workflows the agent can use. They reduce hallucination by giving the agent a known-good way to invoke a multi-step CyberOS operation.

Each prompt is a versioned, audit-anchored workflow; the agent receives the prompt and the bound tool names; the gateway audits prompt invocations separately from individual tool calls.

Architecture

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

graph TB
  subgraph CLIENTS ["Agents (MCP 2025-11-25 clients)"]
    CL_D["Claude Desktop"]
    CL_C["Claude Code CLI"]
    CUR["Cursor / Cline / Codex"]
    CUO["CUO (internal)"]
  end
  subgraph GATEWAY ["MCP Gateway (Rust axum + jsonrpsee)"]
    WK["well_known.rs<br/>/.well-known/oauth-authorization-server<br/>/.well-known/oauth-protected-resource (PRM)"]
    AUTH_E["oauth_edge.rs<br/>OAuth 2.1 PKCE handshake<br/>(delegates to AUTH service)"]
    DISC["discovery.rs<br/>tools/list aggregation"]
    ROUT["federation.rs<br/>tool name -> backend server"]
    ANN["annotations.rs<br/>destructive / readOnly / idempotent"]
    GATE["gate.rs<br/>RBAC + human-confirm + audience check"]
    TASKS["tasks.rs<br/>long-running primitive"]
    ELI["elicitation.rs<br/>mid-execution prompt proxy"]
    AUD["audit.rs<br/>per-call memory write"]
  end
  subgraph BACKENDS ["Per-module MCP servers (HTTP JSON-RPC)"]
    BR["cyberos.memory<br/>update_memory / get_memory / search_memory / ..."]
    SK["cyberos.skill<br/>execute_skill / list_skills / ..."]
    AU["cyberos.auth<br/>get_identity / get_permission / ..."]
    AI["cyberos.ai<br/>execute_chat / generate_embedding / get_usage"]
    CRM["cyberos.crm<br/>(planned, 19 more modules)"]
  end
  subgraph SINKS ["Sinks"]
    AUTHSVC["AUTH service<br/>token issuance + RBAC.Check"]
    memory["memory<br/>mcp.invocation rows"]
    OBS["OBS<br/>traces + metrics"]
  end
  CL_D --> WK
  CL_C --> WK
  CUR --> WK
  CUO --> WK
  WK --> AUTH_E
  AUTH_E --> AUTHSVC
  WK --> DISC
  DISC --> ROUT
  CL_D -->|tools/call| ROUT
  CUR -->|tools/call| ROUT
  ROUT --> ANN
  ANN --> GATE
  GATE --> AUTHSVC
  GATE --> BR
  GATE --> SK
  GATE --> AU
  GATE --> AI
  GATE --> CRM
  ROUT --> TASKS
  GATE --> ELI
  GATE --> AUD
  AUD --> memory
  GATEWAY --> OBS
  classDef planned fill:#e0f2fe,stroke:#0369a1
  classDef backend fill:#cffafe,stroke:#0891b2
  classDef sink fill:#f5ede6,stroke:#45210e
  class WK,AUTH_E,DISC,ROUT,ANN,GATE,TASKS,ELI,AUD,CL_D,CL_C,CUR,CUO planned
  class BR,SK,AU,AI,CRM backend
  class AUTHSVC,memory,OBS sink

Internal components

Data model

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

erDiagram
  SERVER ||--o{ TOOL_DEFINITION: "publishes"
  TOOL_DEFINITION ||--o{ ANNOTATION: "has"
  TOOL_DEFINITION ||--o{ TOOL_INVOCATION: "fulfils"
  TOOL_DEFINITION ||--o{ ELICITATION: "may trigger"
  TOOL_INVOCATION ||--o{ TASK: "may spawn"
  TASK ||--o{ TASK_STATUS_UPDATE: "emits"
  AGENT_CLIENT ||--o{ TOOL_INVOCATION: "calls"
  AGENT_CLIENT ||--o| OAUTH_REGISTRATION: "registered as"
  SERVER {
    string id PK "cyberos.memory"
    string display_name
    string endpoint "https://memory.internal/mcp"
    string version
    string status "active | draining | offline"
    timestamp registered_at
  }
  TOOL_DEFINITION {
    string name PK "cyberos.memory.update_memory"
    string server_id FK
    string description
    obj input_schema "JSON Schema"
    obj output_schema
    string scope_required "memory.update"
  }
  ANNOTATION {
    string tool_name FK
    string key "destructive | readOnly | idempotent | openWorld | titleHuman | requiresConfirm"
    string value
  }
  AGENT_CLIENT {
    uuid id PK
    string display_name "Claude Desktop, Cursor, ..."
    string redirect_uri
    string client_type "public (PKCE) | confidential"
  }
  OAUTH_REGISTRATION {
    uuid client_id FK
    string scopes
    timestamp registered_at
  }
  TOOL_INVOCATION {
    uuid id PK
    string tool_name FK
    uuid agent_id FK
    uuid subject_id "on_behalf_of"
    string persona_version
    string args_hash "SHA-256(canonical)"
    string idempotency_key
    string outcome "ok | denied | error | task_created"
    int latency_ms
    string memory_chain
    timestamp ts
  }
  TASK {
    uuid id PK
    uuid invocation_id FK
    string status "queued | running | completed | failed | cancelled"
    obj progress "fraction / stage / message"
    obj result
    timestamp created_at
    timestamp completed_at
  }
  TASK_STATUS_UPDATE {
    uuid id PK
    uuid task_id FK
    string status
    obj progress
    timestamp ts
  }
  ELICITATION {
    uuid id PK
    uuid invocation_id FK
    string prompt
    obj response_schema
    obj user_response
    timestamp asked_at
    timestamp answered_at
  }

Tool naming convention (SEP-986)

All tool names follow cyberos.{module}.{verb}_{noun}. The verb comes from a closed set of 15 approved SEP-986 verbs (DEC-2361) - get, list, create, update, delete, send, fetch, sync, validate, generate, execute, search, replay, accept, reject; adding one needs a SEP RFC, and a module that registers a tool whose verb is outside the set is refused at registration.

API surface

The gateway speaks MCP 2025-11-25 to agents and forwards tools/call to backends as JSON-RPC over HTTP. A small admin REST surface lets operators inspect the registry and replay invocations.

MCP surface (canonical)

Backend HTTP surface (per-module servers)

There is no separate backend wire protocol: a per-module server is a plain MCP HTTP endpoint. It self-registers its catalogue over the control plane, then the gateway forwards tools/call to the registered endpoint as JSON-RPC 2.0 over HTTP (reqwest).

Registration - POST /v1/mcp/register:

{
  "module": "memory",
  "endpoint": "https://memory.internal/mcp",
  "tools": [
    {
      "name": "cyberos.memory.update_memory",
      "description": "Create or replace a memory file",
      "inputSchema": { "type": "object" },
      "annotations": { "title": "Update memory", "idempotentHint": true },
      "requiresScope": ["mcp:tools"]
    }
  ]
}

The endpoint must be an http:// or https:// URL; any other scheme is rejected at registration. A module keeps its registration live with POST /v1/mcp/heartbeat ({"module": "memory"}) and withdraws with POST /v1/mcp/deregister. The dev slice gates the control plane behind MCP_DEV_REGISTRATION=1; production requires authenticated registration (TASK-MCP-004).

Forwarding - the gateway POSTs a JSON-RPC 2.0 tools/call to the module's registered endpoint:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "cyberos.memory.update_memory", "arguments": {} }
}

The module returns a JSON-RPC result ({ "result": { "content": [ ... ], "isError": false } }). A transport failure, non-2xx status, non-JSON body, or JSON-RPC error envelope maps to the closed error code -32004 module_unreachable.

Admin REST surface (operator-only)

Key flows

Flow 1 - well-known discovery + tool listing

sequenceDiagram
  autonumber
  participant A as Agent (Claude Desktop)
  participant G as MCP Gateway
  participant AS as AUTH service
  participant BR as cyberos.memory (backend)
  participant SK as cyberos.skill
  participant Cache as Catalogue cache
  A->>G: GET /.well-known/oauth-protected-resource
  G-->>A: {resource, authorization_servers, bearer_methods}
  A->>G: GET /.well-known/oauth-authorization-server
  G-->>A: {issuer, authorize/token endpoints, S256, scopes}
  A->>AS: OAuth 2.1 PKCE auth code flow
  AS-->>A: {access_token aud=mcp.cyberos.com}
  A->>G: POST /mcp {jsonrpc "2.0", method "initialize"}
  G-->>A: {capabilities, server_info}
  A->>G: POST /mcp {method "tools/list"}
  G->>Cache: get catalogue
  alt cache hit
    Cache-->>G: full tool list
  else cache miss
    G->>BR: ListTools
    G->>SK: ListTools
    BR-->>G: 12 tools
    SK-->>G: 8 tools
    G->>Cache: SET catalogue TTL=60s
  end
  G-->>A: {tools cyberos.memory.update_memory, cyberos.skill.execute_skill, ...}

The agent sees one server; under the hood, 24 modules contribute their tools. Caching keeps catalogue assembly < 5 ms p95.

Flow 2 - tool invocation with OAuth + RBAC

sequenceDiagram
  autonumber
  participant A as Agent
  participant G as MCP Gateway
  participant GA as gate.rs
  participant AS as AUTH RBAC.Check
  participant BR as cyberos.memory
  participant AUD as audit.rs
  participant B as memory
  A->>G: POST /mcp tools/call cyberos.memory.update_memory {path, body, idempotency_key}
  G->>GA: verify audience claim (mcp.cyberos.com)
  G->>GA: load annotations (destructive=false, scope_required=memory.update)
  GA->>AS: RBAC.Check(subject_jwt, action="memory.update", resource="memories/...")
  AS-->>GA: {allow true, reason "role.founder + scope.memory.update"}
  GA->>BR: POST tools/call {name, arguments}
  BR-->>GA: {result {content, isError}}
  GA-->>A: {content [text], isError false}
  GA->>AUD: write mcp.invocation
  AUD->>B: append row {tool, agent, subject, persona_version, outcome "ok"}

Per-call latency: ~3 ms gateway overhead + backend processing time. The audit write is fire-and-forget; a backlog > 60 s triggers an alert.

Flow 3 - destructive tool with human-confirm gating

sequenceDiagram
  autonumber
  participant A as Agent
  participant G as MCP Gateway
  participant ANN as annotations.rs
  participant ELI as elicitation.rs
  participant U as User UI (CHAT or IDE)
  participant SK as cyberos.skill
  A->>G: tools/call cyberos.skill.execute_skill {skill_id "vietnam-vat-invoice"}
  G->>ANN: load annotations
  ANN-->>G: destructive=true, requiresConfirm=true
  G->>ELI: needs user confirmation
  ELI->>U: "Skill 'vietnam-vat-invoice' will create an invoice in memory. Proceed?"
  alt user approves
    U-->>ELI: {approved true}
    ELI-->>G: proceed
    G->>SK: InvokeTool(...)
    SK-->>G: result
    G-->>A: result
  else user denies
    U-->>ELI: {approved false}
    ELI-->>G: denied
    G-->>A: {error "user_denied", isError true}
  end

(task pending): destructive tool calls without confirmation are rejected. The elicitation UI is rendered by the agent client (Claude Desktop, Cursor) - the gateway is content-agnostic.

Flow 4 - long-running task via the Tasks primitive

sequenceDiagram
  autonumber
  participant A as Agent
  participant G as MCP Gateway
  participant T as tasks.rs
  participant BG as cyberos.kb (backend)
  A->>G: tools/call cyberos.kb.sync_corpus
  G->>BG: InvokeTool(...)
  BG-->>G: {task_id "tsk_01HZJ...XK", expected_ms 120000}
  G->>T: register task tsk_01HZJ...XK
  G-->>A: {task_id, status "running"}
  Note over A: agent receives the task handle and returns control to the user
  loop poll every 2 s
    A->>G: tasks/get {id "tsk_..."}
    G->>BG: TaskStatus(task_id)
    BG-->>G: {status "running", progress 0.34, message "embedding 3,400 / 10k docs"}
    G-->>A: {status "running", progress 0.34, message "..."}
  end
  BG-->>G: {status "completed", result {indexed 10000, elapsed_s 118}}
  A->>G: tasks/get
  G-->>A: {status "completed", result {...}}

(task pending): Tasks primitive for long-running tool invocations. The agent can release the call and resume the conversation; polling fetches updates.

Flow 5 - mid-execution elicitation

sequenceDiagram
  autonumber
  participant A as Agent
  participant G as MCP Gateway
  participant SK as cyberos.skill (vietnam-bank-transfer)
  participant ELI as elicitation.rs
  participant U as User UI
  A->>G: tools/call cyberos.skill.execute_skill {skill "vietnam-bank-transfer", amount 25000000}
  G->>SK: InvokeTool(...)
  SK->>G: elicitation/request {prompt "Confirm transfer of VND 25,000,000 to ACME - please type CONFIRM"}
  G->>ELI: proxy elicitation (with content-safety filter)
  ELI->>U: render prompt in client UI
  U->>ELI: types "CONFIRM"
  ELI-->>G: response {text "CONFIRM"}
  G-->>SK: continue invocation
  SK->>SK: execute transfer
  SK-->>G: result {napas_tx_id "..."}
  G-->>A: result

(task pending): elicitation proxied with a content-safety filter - prevents a compromised backend from injecting prompts that exfiltrate via the user.

Tool-call lifecycle

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.

stateDiagram-v2
  [*] --> Received: agent POSTs /mcp tools/call
  Received --> AudienceOK: aud claim matches gateway
  AudienceOK --> AnnotationLoaded: tool registry hit
  AnnotationLoaded --> RBACChecked: AUTH RBAC.Check
  AnnotationLoaded --> Rejected: tool disabled / unknown
  RBACChecked --> Confirming: destructive + requiresConfirm
  RBACChecked --> Forwarding: readOnly OR confirmed
  Confirming --> Forwarding: user approves
  Confirming --> Denied: user denies
  Forwarding --> Streaming: backend producing chunks
  Forwarding --> TaskCreated: long-running, task_id issued
  TaskCreated --> Polled: agent polls tasks/get
  Polled --> Polled: status running
  Polled --> Completed: status completed
  Polled --> Failed: status failed
  Streaming --> Completed: done frame
  Streaming --> Failed: backend error
  Streaming --> Cancelled: agent / user cancels
  Completed --> Audited: mcp.invocation row written
  Failed --> Audited
  Cancelled --> Audited
  Rejected --> Audited
  Denied --> Audited
  Audited --> [*]

Functional requirements

The CyberOS task catalogue is being rebuilt one feature at a time via the open task-author Agent Skill.

Previous task enumerations were archived 2026-05-14 and are no longer reflected on this page. Specific tasks land here as they are re-authored.

Non-functional requirements

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

Dependencies

graph LR
  subgraph upstream ["MCP Gateway depends on"]
    AUTH["AUTH<br/>token + RBAC.Check"]
    memory["memory<br/>mcp.invocation rows"]
    OBS["OBS<br/>traces + metrics"]
    PG["PostgreSQL<br/>tool registry"]
    REDIS["Redis<br/>catalogue + tasks cache"]
  end
  MCP["MCP Gateway"]
  subgraph backends ["Per-module servers"]
    BR["cyberos.memory"]
    SK["cyberos.skill"]
    AU["cyberos.auth"]
    AI["cyberos.ai"]
    OTH["+20 more"]
  end
  subgraph clients ["MCP clients"]
    CL["Claude Desktop"]
    CC["Claude Code"]
    CUR["Cursor / Cline / Codex"]
    INT["Internal agents"]
  end
  AUTH --> MCP
  memory --> MCP
  OBS --> MCP
  PG --> MCP
  REDIS --> MCP
  MCP --> BR
  MCP --> SK
  MCP --> AU
  MCP --> AI
  MCP --> OTH
  CL --> MCP
  CC --> MCP
  CUR --> MCP
  INT --> MCP
  classDef shipped fill:#f5ede6,stroke:#45210e
  classDef planned fill:#fef6e0,stroke:#9c750a
  class memory,SK,REDIS,PG shipped
  class MCP,AUTH,AI,AU,BR,OTH,OBS planned
  class CL,CC,CUR,INT shipped

Compliance scope

Risk entries

KPIs

RACI matrix

Planned CLI surface

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.memory 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.memory.delete_memory

name: cyberos.memory.delete_memory
server: cyberos.memory
description: "Delete a memory file (tombstone by default; purge requires DSAR reason)"
scope_required: memory.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.memory.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 pass (12 / 12)
 tools/list pass (18 / 18)
 tools/call pass (24 / 24)
 resources/* pass (16 / 16)
 prompts/* pass (14 / 14)
 completion/complete pass (8 / 8)
 tasks/* pass (12 / 12)
 elicitation/* pass (10 / 10)
 sampling/* pass (6 / 6)
 oauth (pkce) pass (14 / 14)
 prm pass (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 https://crm.internal/mcp \
 --version 0.3.0 \
 --manifest crm-tools.json \
 --approval-jira CYB-1234

[validate] manifest: 11 tools, SEP-986 ok, annotations ok
[approve] CTO + CSO approved (per CYB-1234)
[register] cyberos.crm registered
[catalog] cache invalidated
[audit] memory seq=14856

Phase status & estimates

• Status: planned - P0, design phase; P0 slice 3
• Est. LoC (Rust): ~5,500 - services/mcp-gateway
• Planned tests: 142 conformance + 60 unit - MCP spec suite
• P0 tools (est.): ~80 - memory, Skill, AUTH, AI
• P3 tools (est.): ~300+ - 24 modules x ~15 verbs
• CLI commands: ~18 planned - cyberos-mcp

References

• Bigger picture (above): 3 strategic roles + federation diagram + auto-vs-human matrix.
• External-client federation (above): SEP-986 naming + module registration sequence + 6-row client compatibility matrix.
• Capability broker (above): 6-row tool-annotation gating + audience-bound OAuth JWT + destructive-op confirmation flow with Elicitation.
• Tool-discovery surface (above): 6 discovery endpoints + the Tasks primitive 8-field schema + 5 pre-canned prompt templates.
• Cross-module page links: auth.html, cuo.html, memory.html, skill.html, ai.html, obs.html, proj.html, chat.html
• Build-readiness audit: archive/2026-05-14/AUDIT_AND_PLAN.md (archived; see cyberos/CHANGELOG.md) - MCP Gateway placed at P0 slice 3 in the P0 sequence (after AI Gateway + AUTH stub).
• Research review: archive/2026-05-14/RESEARCH_REVIEW.md (archived; see cyberos/CHANGELOG.md) - MCP Gateway rated "Strong" (9/10); the reviewer flagged the elicitation-fatigue risk (R-MCP-013) and the older-protocol sunset as the two operational concerns.
• Memory auto-sync vision: MEMORY_AUTOSYNC_DESIGN.md §5 - MCP tool invocations are one of four canonical capture surfaces for the local memory (every tool call -> audit row); §6 - Lumi exposes cross-tenant MCP federation at P3+ for org-tenant agents.
• task authoring discipline: modules/skill/task-audit/AUTHORING_DISCIPLINE.md - MCP Gateway tasks land via the task-author Agent Skill.
• MCP Specification 2025-11-25 - modelcontextprotocol.io/specification/2025-11-25.
• SEP-986 - verbNoun.dotted tool naming convention.
• RFC 6749 / draft-ietf-oauth-v2-1 - OAuth 2.1.
• RFC 7591 - Dynamic Client Registration.
• RFC 7636 - Proof Key for Code Exchange (PKCE).
• RFC 9112 - HTTP/1.1 (chunked transfer).
• RFC 9728 - OAuth 2.0 Protected Resource Metadata.
• DPoP (RFC 9449) - device-binding tokens at P2+.
• EU AI Act - Art. 12 logging, Art. 13 transparency, Art. 14 human oversight, Art. 26 deployer obligations.
• Vietnam PDPL (Law 91/2025): Art. 14 (DSAR via mcp.invocation export), Art. 20 (security obligations).
• OWASP Gen AI Top-10 (2025) - LLM02, LLM07, LLM08 mitigations.
• Architecture context: infrastructure.html#mcp.

Previous: AI Gateway | Next module: Observability

Changelog

History lives in the changelog; this page describes only the current state.

Generated from services/mcp-gateway/docs/index.md — edit the markdown source, not this file (TASK-DOCS-002).