Quickstart

Get ArcaX running locally in under 5 minutes using Docker Compose.

1. Authenticate & Start

# License key required — request at www.arcax.ai/#demo
docker login registry.arcax.ai --username $ARCAX_LICENSE_KEY
curl -sO https://install.arcax.ai/docker-compose.yml
cp .env.example .env
docker compose up -d

This starts: gateway (port 8000), postgres, redis, dashboard (port 3000).

2. Register your first source

curl -X POST http://localhost:8000/api/v1/sources \
  -H "Content-Type: application/json" \
  -d '{
    "name": "petstore",
    "type": "openapi",
    "config": {
      "spec_url": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  }'

3. List generated MCP tools

curl http://localhost:8000/api/v1/tools | jq '.tools[].name'

4. Call a tool

curl -X POST http://localhost:8000/mcp/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "petstore.getPetById", "params": {"petId": 1}}'

Installation

ArcaX is distributed as container images. Production deployments use Kubernetes with Helm.

Docker Compose (Dev / PoC)

docker compose -f docker-compose.yml up -d

Kubernetes (Production)

helm repo add arcax https://charts.www.arcax.ai
helm install arcax arcax/arcax \
  --namespace arcax --create-namespace \
  -f values-prod.yaml

Air-Gap Installation

# Export images for offline transfer
docker save arcax/gateway:latest | gzip > arcax-gateway.tar.gz
docker save arcax/dashboard:latest | gzip > arcax-dashboard.tar.gz

# On air-gapped machine
docker load < arcax-gateway.tar.gz
docker load < arcax-dashboard.tar.gz

Configuration

Key environment variables in .env:

Architecture

ArcaX implements a 5-stage deterministic mediation pipeline that converts any enterprise data source into a certified MCP tool set.

Pipeline Stages

1. Probe — introspects the source (OpenAPI spec fetch, SQL INFORMATION_SCHEMA query, SAP CDS introspection, or COBOL copybook parse).
2. Universal Capability Schema (UCS) — a source-agnostic JSON pivot format capturing endpoints, parameters, data types, and auth requirements.
3. Contextualise — applies field-level transformations (type coercion, date normalisation, EBCDIC decoding) and injects OPA policy stubs per tool.
4. MCP Generate — emits Python code: Pydantic v2 models + FastMCP @mcp.tool() decorators — all generated at runtime, no codegen step.
5. JIT Cache — writes compiled tool to L1 (in-process dict) and L2 (Redis SETEX). Subsequent calls bypass all stages. Cache invalidated via pub/sub on source update.

Universal Capability Schema (UCS)

The Universal Capability Schema is the internal pivot format produced at stage 2 of the mediation pipeline. It is the single normalised representation that all downstream stages (Contextualise, MCP Generate, JIT Cache) consume — regardless of whether the source is a REST API, a SQL database, a SAP BAPI, a COBOL copybook or a Kafka topic.

Why a pivot format?

Enterprise sources expose radically different schemas: OpenAPI paths, INFORMATION_SCHEMA tables, SAP CDS views, COBOL copybooks, Avro topics. Without a common representation, every downstream component would need to handle every source type. UCS decouples source heterogeneity from tool generation: probes write UCS, everything else reads UCS.

Structure

A UCS document has three top-level layers:

• Header — source_uri, source_type, version
• Operations — the list of discovered capabilities (endpoints, tables, BAPIs, topics…)
• Raw metadata — verbatim probe output preserved for auditability

Each operation contains:

• name — canonical snake_case identifier used as the MCP tool name
• description — human-readable description surfaced in the MCP tool manifest
• inputs / outputs — typed field lists (see below)
• source_ref — original reference (GET /orders, TABLE orders, BAPI_SALESORDER_GETLIST…)

Each field carries:

• technical_name — original name in the source system
• business_name — enriched human label (filled by the Contextualise stage)
• data_type — normalised type string: string, integer, number, boolean, date, object
• nullable — whether the field is optional
• metadata — arbitrary key/value pairs (PII flag, GDPR category, EBCDIC picture clause, SAP domain, etc.)

Example — REST source

{
  "source_uri": "https://api.acme.com/v2",
  "source_type": "rest",
  "version": "1.0",
  "operations": [
    {
      "name": "list_orders",
      "description": "List customer orders with optional filters",
      "source_ref": "GET /orders",
      "inputs": [
        { "technical_name": "customer_id", "data_type": "string",  "nullable": true },
        { "technical_name": "status",      "data_type": "string",  "nullable": true },
        { "technical_name": "limit",       "data_type": "integer", "nullable": true }
      ],
      "outputs": [
        { "technical_name": "id",          "data_type": "string",  "nullable": false },
        { "technical_name": "total",       "data_type": "number",  "nullable": false },
        { "technical_name": "created_at",  "data_type": "date",    "nullable": false }
      ]
    }
  ],
  "raw_metadata": { "openapi_version": "3.1.0", "paths_count": 47 }
}

Zero-Trust Security

Auto-PKI Bootstrap

make certs-init  # generates ca.key, ca.crt + node certs

On first start, AutoEnrollment issues 1-hour ephemeral leaf certificates JIT. Private keys are kept in memory only (or in HSM if HSM_LIB_PATH is set).

OPA Policy Example

package arcax.tool

default allow = false

allow {
  input.tenant_id == data.tenants[_].id
  input.tool_name in data.products[input.product_id].allowed_tools
}

Payload Signing Verification

import nacl.signing
import json, base64

pub_key_b64 = "..."  # from GET /api/v1/keys/public
verify_key = nacl.signing.VerifyKey(base64.b64decode(pub_key_b64))

response = json.loads(tool_response_body)
sig = base64.b64decode(response["__sig__"])
verify_key.verify(json.dumps(response["data"]).encode(), sig)

FinOps & ROI Tracking

Every tool call emits a UsageTick event:

{
  "tenant_id": "acme",
  "source_id": "erp-sap",
  "tool_name": "get_sales_order",
  "bytes_in": 128,
  "bytes_out": 4096,
  "duration_ms": 45,
  "timestamp": "2026-04-12T08:30:00Z",
  "cost_unit": 0.0012
}

Query aggregated usage:

GET /api/v1/finops/usage?tenant=acme&period=30d&group_by=source

UAM Pipeline

The Universal Agent Mediation pipeline converts any enterprise source into certified MCP tools via 5 deterministic stages.

Trigger / inspect via API

# Re-run pipeline for a source
POST /api/v1/sources/{id}/refresh

# Response
{
  "pipeline_run_id": "run_01j...",
  "stages": {
    "probe": {"status": "ok", "duration_ms": 187},
    "ucs":   {"status": "ok", "duration_ms": 44},
    "ctx":   {"status": "ok", "duration_ms": 31},
    "gen":   {"status": "ok", "duration_ms": 76},
    "cache": {"status": "ok", "duration_ms": 9}
  },
  "tools_generated": 12
}

# Run stages 1-2 only (debug)
GET /api/v1/sources/{id}/probe

JIT Cache

A two-tier cache serves compiled MCP tools in <1 ms after the first pipeline run. No reprocessing on repeated calls.

Cache invalidation

# Automatic: pub/sub on source update
# Redis channel: arcax:cache:invalidate
# Payload: {"source_id": "erp-sap", "version": 4}

# Manual
DELETE /api/v1/sources/{id}/cache
# {"invalidated": true, "keys_removed": 2}

Warm-up on startup

Set CACHE_WARMUP=true to pre-populate L1 from L2 on gateway boot — eliminates cold-start latency.

Source Registry

PostgreSQL-backed catalogue of all registered sources, their versioned tool snapshots, and lifecycle states.

Lifecycle

draft → probing → active → archived

# List active sources
GET /api/v1/sources?status=active

[{
  "id": "erp-sap", "name": "SAP S/4HANA", "type": "sap",
  "status": "active", "tools_count": 23, "version": 4,
  "last_synced": "2026-04-12T08:00:00Z"
}]

Versioning & rollback

# Rollback to a previous version
POST /api/v1/sources/{id}/rollback
{"version": 3}

# Export OpenAPI 3.1 spec from any version
GET /api/v1/sources/{id}/openapi?version=3

Tool filtering

PATCH /api/v1/sources/{id}
{
  "tool_filter": ["get_sales_order", "list_materials"],
  "tool_prefix": "sap."
}

Self-Healing Mediation

ArcaX continuously watches every registered source for schema drift. When the source changes — a new column, a renamed endpoint, an updated copybook — the affected MCP tools are regenerated automatically. Zero restart, zero manual intervention.

Watchers per source type

Self-healing cycle

1. Drift detection — a watcher flags a schema change in under 30 seconds.
2. Debounce (30 s) — consecutive change events within a 30-second window are coalesced, so a batch migration triggers a single regeneration, not dozens.
3. JIT cache invalidation — the compiled tools for the source are evicted from L1 and L2 (pub/sub channel arcax:cache:invalidate).
4. Automatic re-generation — the 5-stage UAM pipeline re-runs (Probe → UCS → Contextualise → MCP Generate → JIT Cache) and the fresh tools go live.

REST / OpenAPI Connector

Introspects any OpenAPI 3.0/3.1 spec and generates one MCP tool per operation.

Registration

POST /api/v1/sources
{
  "name": "petstore",
  "type": "openapi",
  "config": {
    "spec_url": "https://petstore3.swagger.io/api/v3/openapi.json",
    "base_url": "https://petstore3.swagger.io",
    "auth": {"type": "bearer", "token_env": "PETSTORE_API_KEY"}
  }
}

Auth methods

Database Connectors

ArcaX introspects INFORMATION_SCHEMA to generate MCP tools for queries on tables and views.

POST /api/v1/sources
{
  "name": "warehouse-db",
  "type": "postgres",
  "config": {
    "connection_url_env": "WAREHOUSE_DB_URL",
    "schema": "public",
    "table_filter": ["orders", "products", "inventory"],
    "read_only": true
  }
}

SAP / ERP Connector

Native RFC/BAPI connectivity via PyRFC, plus CDS / OData for S/4HANA. Kyriba supported via OpenAPI.

SAP RFC / BAPI

POST /api/v1/sources
{
  "name": "sap-s4",
  "type": "sap",
  "config": {
    "ashost_env": "SAP_ASHOST",
    "sysnr": "00",
    "client": "100",
    "user_env": "SAP_USER",
    "passwd_env": "SAP_PASSWD",
    "bapi_filter": ["BAPI_SALESORDER_*", "BAPI_MATERIAL_*"]
  }
}

S/4HANA OData

{
  "type": "sap_odata",
  "config": {
    "base_url": "https://s4hana.corp.local/sap/opu/odata/sap/",
    "service": "API_SALES_ORDER_SRV",
    "auth": {
      "type": "basic",
      "username_env": "SAP_USER",
      "password_env": "SAP_PASSWD"
    }
  }
}

Kyriba (Treasury)

{
  "type": "openapi",
  "config": {
    "spec_url": "https://api.kyriba.com/openapi/v1/openapi.json",
    "auth": {
      "type": "oauth2_client",
      "token_url": "https://api.kyriba.com/oauth/token",
      "client_id_env": "KYRIBA_CLIENT_ID",
      "client_secret_env": "KYRIBA_CLIENT_SECRET"
    }
  }
}

Mainframe Connector

Connects to IBM z/OS via TN3270 terminal emulation. COBOL copybooks are parsed to generate fully-typed Pydantic models.

POST /api/v1/sources
{
  "name": "mainframe-cics",
  "type": "mainframe",
  "config": {
    "host_env": "MF_HOST",
    "port": 23,
    "lu_name": "LUA00001",
    "copybook_dir": "/etc/arcax/copybooks/",
    "encoding": "EBCDIC",
    "transaction_map": {
      "get_account":       "ACCT",
      "list_transactions": "TXNL"
    }
  }
}

COBOL copybook → Pydantic

       01 ACCOUNT-RECORD.
          05 ACCT-ID      PIC X(10).
          05 ACCT-BALANCE PIC S9(13)V99 COMP-3.
          05 ACCT-DATE    PIC 9(8).

# Generated model
class AccountRecord(BaseModel):
    acct_id:      str     # max_length=10
    acct_balance: Decimal # COMP-3 packed decimal
    acct_date:    date    # YYYYMMDD auto-parsed

Capital Markets / Fintech Connectors

ArcaX includes 12 native connectors for capital markets, post-trade and insurance platforms. All follow the same JIT mediation pipeline, OPA governance and FinOps metering.

Supported platforms

Registration example — BlackRock Aladdin

curl -X POST http://localhost:8000/sources/register \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "source_uri": "aladdin://aladdin.blackrock.com",
    "label": "Aladdin Risk Platform",
    "tenant_id": "acme",
    "tags": ["risk", "portfolio", "fintech"]
  }'

mTLS-enabled connectors (SWIFT / DTCC)

SWIFT gpi and DTCC require mTLS in addition to OAuth2. Set the certificate paths before starting the gateway:

export SWIFT_CERT_PATH=/etc/arcax/certs/swift-client.pem
export SWIFT_KEY_PATH=/etc/arcax/certs/swift-client.key
export SWIFT_CLIENT_ID=my-client-id
export SWIFT_CLIENT_SECRET=my-secret

Telecom / OSS-BSS Connectors

ArcaX includes 10 native connectors for telecom OSS/BSS platforms. All connect via Bearer-token REST and follow the same JIT mediation pipeline, OPA governance and FinOps metering.

Supported platforms

Registration example — Ericsson ENM

curl -X POST http://localhost:8000/sources/register \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "source_uri": "ericsson://enm.corp.internal",
    "label": "Ericsson ENM Prod",
    "tenant_id": "acme",
    "tags": ["telecom", "ran", "oss"]
  }'

Environment variables

OPA Policies

Every tool call is evaluated by Open Policy Agent before execution. Policies are hot-reloaded — no gateway restart needed.

Input schema

{
  "tenant_id":  "acme",
  "agent_id":   "claude-3-7",
  "product_id": "prod_enterprise",
  "tool_name":  "sap.get_sales_order",
  "source_id":  "sap-s4",
  "params":     {"order_id": "0000012345"},
  "timestamp":  "2026-04-12T08:30:00Z",
  "ip":         "10.0.1.5"
}

Example policy

package arcax.tool
import future.keywords

default allow := false

allow if {
  product := data.products[input.product_id]
  input.tool_name in product.allowed_tools
  input.tenant_id == product.tenant_id
}

# Block salary field access for non-HR agents
deny if {
  input.tool_name == "workday.get_employee"
  not input.agent_id in data.hr_agents
}

Push a policy update

PUT /api/v1/opa/policies/arcax.tool
Content-Type: text/plain

# Rego content here...

# Response
{"updated": true, "reloaded_at": "2026-04-12T09:00:00Z"}

ArcaX ships with an embedded OPA sidecar. For external clusters, set OPA_URL in .env.

HSM Integration

PKCS#11 HSM support for production key management. Private keys never leave the hardware boundary.

Configuration

# .env
HSM_LIB_PATH=/usr/lib/softhsm/libsofthsm2.so   # or vendor lib
HSM_TOKEN_LABEL=arcax-pki
HSM_PIN_ENV=HSM_PIN

Test with SoftHSM2

apt install softhsm2
softhsm2-util --init-token --slot 0 --label arcax-pki \
  --so-pin 0000 --pin 1234

# Verify objects
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login --pin 1234 --list-objects

Key operations with HSM active

• CA key is generated inside the HSM at make certs-init — never exported
• Leaf certificate signing uses PKCS#11 C_Sign
• Ed25519 payload signatures use the HSM-backed key handle
• Dashboard shows 🔒 HSM Active badge in the settings panel

OpenTelemetry

ArcaX emits OTLP traces, metrics, and audit logs with end-to-end trace propagation across inbound requests and outbound HTTP clients.

Configuration

# .env
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_SERVICE_NAME=arcax-gateway
OTEL_SERVICE_VERSION=0.5.0
DEPLOY_ENV=production
OTEL_EXPORTER_OTLP_INSECURE=false
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=1.0

Trace spans

Metrics

mcp_latency (histogram, ms)
pki_verification_success
mcp_traffic_kb_day

# Optional Prometheus endpoint if enabled in your deployment
GET /metrics

arcax_tool_calls_total{tenant,source,tool,status}
arcax_tool_duration_seconds{quantile="0.99"}
arcax_cache_hit_ratio{tier="L1|L2"}
arcax_pipeline_duration_seconds
arcax_budget_used_ratio{tenant,source}

Logs pipeline

ArcaX bridges the audit logger to OTLP logs. Ensure your collector has a logs pipeline (receiver otlp + exporter).

Full observability stack (Docker Compose)

docker compose \
  -f docker-compose.yml \
  -f docker-compose.otel.yml \
  up -d
# Adds: otel-collector, Prometheus, Grafana (port 3001)

Kubernetes

The ArcaX runtime deploys as a constellation of single-purpose pods. The Helm chart deploys Core, Security, Governance, Observability, Executor and Pod Manager fabrics, plus the dedicated SOC pod constellation (collector, analyzer, responder, forensics, dashboard), OPA, Redis, PostgreSQL, Kafka and optional TimescaleDB. Tool execution runs in the dedicated Executor fabric: the core gateway delegates source calls to it through a strangler facade, so the gateway stays stateless and horizontally scalable. KEDA scales each pod independently on its own Kafka lag. Download the chart from your licensed distribution or private registry.

Install

# Obtain the ArcaX Kubernetes manifests from your licensed distribution
cd arcax-k8s

helm install arcax . \
  --namespace arcax --create-namespace \
  --set license.key=$ARCAX_LICENSE_KEY \
  -f values.yaml -f values-prod.yaml

Key values.yaml options

gateway:
  replicas: 3
  resources:
    requests: { cpu: "500m", memory: "512Mi" }
    limits:   { cpu: "2",    memory: "2Gi"   }

redis:
  enabled: true
  architecture: replication

opa:
  enabled: true
  replicas: 2

pki:
  hsm:
    enabled: false
    libPath: ""

otel:
  enabled: true
  endpoint: "http://otel-collector:4317"

Probes

livenessProbe:
  httpGet: { path: /health, port: 8000 }
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet: { path: /ready, port: 8000 }
  initialDelaySeconds: 5
  periodSeconds: 10

Air-gap

# Mirror images to private registry
crane copy registry.arcax.ai/gateway:latest \
  registry.corp.local/arcax/gateway:latest

# Override in values.yaml
global:
  imageRegistry: registry.corp.local

HAM — Hybrid Agentic Manager

The HAM MCP server exposes 17 governance operations as callable MCP tools. Any MCP-compatible agent holding the ham:admin scope can issue tokens, manage subscriptions, control licenses, and drive the full agent lifecycle — no separate API integration required.

Tool groups

Traceability

Every HAM tool response carries an X-Trace-Id header, forwarded end-to-end for correlation. The ham:admin scope is enforced on every call, and each operation is written to the immutable audit log — every governance action is auditable.

Kimi LLM Integration

ArcaX integrates the Kimi / Moonshot LLM via the OpenAI-compatible protocol to assist onboarding and operations.

Capabilities

• Automatic source detection — POST /api/llm/sources/suggest analyses a source description and suggests the matching connector type and configuration. Credentials are never sent to the LLM.
• Kubernetes diagnostics — LLM-assisted analysis of pod state, events, and logs to surface probable causes and remediation hints.
• OpenAI-compatible provider — Kimi / Moonshot is reached through the standard chat-completions interface, so the integration works with any OpenAI-compatible endpoint.

API Reference

Full OpenAPI 3.1 spec available at runtime:

curl http://localhost:8000/openapi.json | jq .

Interactive Swagger UI at: http://localhost:8000/docs

Core endpoints