Architecture

This page is for the cloud, security, or platform architect evaluating AgentCube before installing it: where it runs, what crosses each trust boundary, how identity reaches Oracle, and what data is — and is not — stored. For a higher-level orientation, start with the Overview.

System topology

AgentCube is built around the Context Engine — a hub the AI assistant connects to as a single MCP endpoint. The Context Engine registers your connectors, routes each request to the right backend, and presents a compact set of about five generic tools to the assistant rather than a separate tool surface per connector. The connectors sit behind it as data adapters that speak Oracle’s native REST APIs.

graph LR
    subgraph client["AI Platform"]
        AI["AI Assistant<br/>(Claude, Copilot,<br/>ChatGPT, Gemini, …)"]
    end

    subgraph env["Your environment"]
        direction TB
        CE["Context Engine<br/>(single MCP endpoint,<br/>~5 generic tools)"]
        P["Planning<br/>adapter"]
        F["FCCS<br/>adapter"]
        E["Essbase<br/>adapter"]
        CE --> P
        CE --> F
        CE --> E
    end

    subgraph oracle["Oracle EPM"]
        OP["EPM Planning Cloud"]
        OF["FCCS"]
        OE["Essbase 21c"]
    end

    AI -- "MCP (HTTPS)" --> CE
    P -- "REST (HTTPS)" --> OP
    F -- "REST (HTTPS)" --> OF
    E -- "REST (HTTPS)" --> OE

The AI assistant talks only to the Context Engine; it never addresses a connector directly. Connectors are reachable only from the Context Engine inside your environment.

Model Context Protocol

MCP is an open protocol that standardizes how AI assistants connect to external systems. The Context Engine implements the MCP server specification, so any MCP-compatible client can connect without custom integration — you are not locked into one AI platform.

Connectors

Connectors are the data adapters behind the Context Engine — one per Oracle system. They translate the Context Engine’s generic tool calls into each system’s native REST API and return results; they hold no business state of their own.

Connector	Oracle system
Planning	Oracle EPM Planning Cloud (EPBCS/PBCS)
Essbase	Oracle Essbase 21c
FCCS	Oracle Financial Consolidation & Close

FCCS is the newest connector.

For the EPM connectors, the metadata/schema surface and the end-user data surface are served by separate connector instances — an admin instance (browse hierarchies, enumerate structure) and a user instance (query data, governed by per-user identity). Treat them as two distinct workloads when you plan network reachability and credentials.

Deployment topology

AgentCube is self-hosted: you run it entirely inside your own environment, alongside your Oracle EPM stack. The Context Engine and the connectors ship as Docker container images that you pull from a private container registry (GHCR), authenticating with a Caprus-provided access token, and run on the container platform of your choice — Azure Container Apps, AWS ECS, OCI Container Instances, Kubernetes, or plain Docker.

Runtime characteristics:

• Containerized — standard Linux containers; each listens on port 8080 and runs as a non-root user.
• TLS at the edge — containers serve plain HTTP on 8080; your platform’s ingress (load balancer / reverse proxy) terminates TLS in front of them.
• Connectors are stateless — no local database, no persisted business data; they can be restarted or scaled horizontally without data loss.
• The Context Engine is stateful — it is backed by a PostgreSQL database you provision and operate, holding the connector registry, the metadata cache, and the audit log (see Data in, data out). Plan for it as a persistent, backed-up workload.

The only thing in this topology that calls out to Caprus is optional license validation: if you configure a license key, the Context Engine validates it with Caprus’s licensing service at startup and periodically, transmitting only the license key and a deployment fingerprint — never business data — and continuing to serve if that service is unreachable. Otherwise nothing calls home: you pull images at deploy time, and from then on traffic stays between the AI platform, your Context Engine, your connectors, and your Oracle systems.

For how to size and run this topology in production — replica counts, resource tiers, high availability, and a day-2 runbook — see Production Deployment & Sizing.

Trust boundaries

There are three boundaries an architect should map, each crossed only over TLS:

Boundary	What crosses it	Notes
AI platform → Context Engine	MCP request carrying the caller’s identity	The single inbound entry point. In production, authenticated as an OAuth 2.1 / OIDC resource server.
Context Engine → connector	A scoped, per-call request with user identity attached	Connectors are not exposed to the AI platform directly; they trust only the Context Engine.
Connector → Oracle	A native REST call, authenticated as the user or a service account	Oracle enforces its own authorization on every call (see below).

All three legs stay inside your environment except the AI platform itself. No customer data is sent to Caprus, and the Context Engine emits no usage telemetry upstream.

Authentication and identity

Identity is established at the inbound edge and carried through to Oracle, so Oracle’s native security applies to every call. In production, the Context Engine validates each inbound MCP request as an OAuth 2.1 / OIDC resource server against your identity provider; an unauthenticated mode exists for local development only.

How the call is attributed in Oracle’s own audit depends on which identity posture you choose for the connector:

Posture	How it works	Oracle sees	IdP required
Service account	A single shared credential authenticates every call.	One service account for all users.	No
Delegated user credential	The Context Engine stores each user’s Oracle credential (encrypted) and forwards it per call.	The named user.	No
Federated SSO	The user authenticates via corporate SSO; the per-user token is exchanged for a user-scoped Oracle token (JWT-bearer assertion).	The named user.	Yes (any OIDC IdP)

Both delegated and federated postures preserve per-user attribution end to end — the user named in the Context Engine’s audit log is the user Oracle records. The federated posture stores no Oracle credentials at all. User-facing data instances require a per-user posture; the shared service account is reserved for metadata/admin or single-team use.

For the full authentication model and the end-to-end identity flow, see Security → Authentication & Identity.

SSO data flow

sequenceDiagram
    participant User
    participant AI as AI Platform
    participant IdP as Identity Provider
    participant CE as Context Engine
    participant Conn as Connector
    participant Oracle as Oracle EPM

    User->>AI: Ask a question
    AI->>IdP: Authenticate (OIDC)
    IdP-->>AI: Identity token ([email protected])
    AI->>CE: MCP request + identity token
    CE->>CE: Validate token, resolve user
    CE->>Conn: Routed call + user identity
    Conn->>Oracle: REST call as the user (exchanged token)
    Oracle-->>Conn: Data (filtered by user entitlements)
    Conn-->>CE: Results
    CE-->>AI: Response
    AI-->>User: Only data the user is entitled to

Data in, data out

• No business data is persisted. Member-level financial data is fetched on demand and streamed back to the AI session; it is never written to the Context Engine’s database or to a connector. Every data query hits Oracle fresh.
• Metadata is cached. The Context Engine caches structural facts — which dimensions and hierarchies exist — to keep responses fast. This is metadata only, not member data, and it stays in your database.
• A tamper-evident audit log of admin actions and routed calls is recorded in the Context Engine’s database, attributed to the acting user, and kept on your side for your own review.
• Credentials are encrypted at rest in the Context Engine’s database; no plaintext secrets are stored.
• Nothing leaves to Caprus, and no AI training occurs on data that passes through AgentCube.

Security principles

• Source-native authorization — AgentCube implements no authorization rules of its own. If Oracle does not let a user see something, neither does AgentCube.
• Encrypted in transit — every hop uses HTTPS/TLS: AI platform → Context Engine, Context Engine → connector, and connector → Oracle.
• Per-user isolation — under per-user postures, each user’s tokens and sessions are kept separate; one user’s credentials are never served to another, even under concurrent load.
• Least privilege at the edge — containers run as a non-root user on an unprivileged port, with TLS terminated by your platform.

For the full treatment — data handling and retention, isolation guarantees, and the shared-responsibility model — see the Security section.

Supported platforms

Data sources

System	Version
Oracle EPM Planning Cloud	EPBCS / PBCS
Oracle Essbase	21c
Oracle FCCS	Cloud

FCCS is the newest connector.

AI platforms

Any client that supports the Model Context Protocol, including Anthropic Claude (claude.ai, Claude Code), Microsoft Copilot Studio, OpenAI ChatGPT, Google Gemini, and other MCP-compatible clients.

Container platforms

Any platform that runs Linux containers — Azure Container Apps, AWS ECS, Google Cloud Run, Kubernetes (AKS, EKS, GKE, self-hosted), OCI Container Instances, or Docker.

Identity providers (federated SSO)

Any OIDC-compliant provider — Microsoft Entra ID, Okta, Auth0, Keycloak, Ping Identity, or any provider supporting OAuth 2.0 / OpenID Connect.