Aris

Software AG ARIS REST API + MCP Server + A2A Server for Agentic AI.

aris-mcp connects the agent ecosystem to an ARIS tenant (ARIS Connect / ARIS Enterprise / ARIS Cloud). It is the inbound and outbound bridge for the agent-utilities Knowledge Graph's Camunda + ARIS ↔ KG integration:

• Inbound — the KG ARIS extractor (enrichment/extractors/aris.py) consumes this client to lift ARIS models + their EPC structure (functions → BusinessTask, rule operators → gateways, events collapsed, connections → FLOWS_TO) into the canonical ArchiMate ontology, where they reconcile with Camunda/Egeria via ALIGNED_WITH and are reasoned over in OWL/RDF.
• Outbound — the KG process-intelligence writeback (enrichment/process_writeback.py) uses set_model_attributes to write a kg_intelligence attribute back onto ARIS models (gated by ARIS_ENABLE_WRITE).

Available MCP Tools

The table below is auto-generated from the live server — do not edit by hand.

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

MCP Tool	Toggle Env Var	Description
aris_ingest_model_export	ARISTOOL	Store a raw ARIS model export (bytes) as a content-addressed KG blob.
aris_ingest_models	ARISTOOL	Natively ingest ARIS models into epistemic-graph as typed nodes.
aris_model	ARISTOOL	Work with ARIS models and their EPC structure.
aris_object	ARISTOOL	Write attributes on a single ARIS object.

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

7 per-operation tools — one per public API method (click to expand)

MCP Tool	Toggle Env Var	Description
aris_get_model	ARIS_APITOOL	Get a single model's metadata (including its attributes).
aris_list_model_attributes	ARIS_APITOOL	Get a model's attributes (used for writeback idempotency read-back).
aris_list_model_connections	ARIS_APITOOL	List the directed control-flow connections between a model's objects.
aris_list_model_objects	ARIS_APITOOL	List the EPC objects (functions/events/rule operators) of a model.
aris_list_models	ARIS_APITOOL	List models in the tenant/database (process + architecture).
aris_set_model_attributes	ARIS_APITOOL	Write/update attributes on a model (e.g. the kg_intelligence blob).
aris_set_object_attributes	ARIS_APITOOL	Write/update attributes on a single object.

4 action-routed tool(s) · 7 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Writes require ARIS_ENABLE_WRITE=True.

Environment Variables

Package environment variables

Variable	Example	Description
ARIS_API_BASE	http://localhost/abs/api	ARIS REST base URL (tenant API root). Default follows the ARIS Connect ABS layout.
ARIS_SSL_VERIFY	True	Verify TLS (set False for self-signed / homelab tenants)
ARIS_OAUTH_URL	—	1. OAuth2 client-credentials (preferred for ARIS Cloud / Connect)
ARIS_CLIENT_ID	—
ARIS_CLIENT_SECRET	secret-injected
ARIS_TENANT	—
ARIS_TOKEN	secret-injected	2. Static bearer token (alternative to OAuth)
ARIS_USERNAME	—	3. HTTP basic auth (alternative)
ARIS_PASSWORD	secret-injected
ARIS_PATHS_JSON	—	Optional JSON overriding the default ARIS REST path templates per tenant e.g. {"models":"v2/repository/models","model_objects":"v2/models/{model_id}/objects"}
ARIS_ENABLE_WRITE	False	Allow (gated) attribute writes back onto ARIS models (KG writeback)
TRANSPORT	stdio	stdio, streamable-http, or sse
HOST	0.0.0.0
PORT	8000
MCP_TOOL_MODE	condensed	Tool surface: condensed, verbose, or both
MCP_ENABLED_TOOLS	—	Comma-separated tool / tag allow/deny lists
MCP_DISABLED_TOOLS	—
MCP_ENABLED_TAGS	—
MCP_DISABLED_TAGS	—
DEBUG	False
PYTHONUNBUFFERED	1
ARISTOOL	True	The action-routed ARIS tools (aris_model, aris_object) share this toggle.
ENABLE_OTEL	True
OTEL_EXPORTER_OTLP_ENDPOINT	—
OTEL_EXPORTER_OTLP_PROTOCOL	—
EUNOMIA_TYPE	none
EUNOMIA_POLICY_FILE	mcp_policies.json
EUNOMIA_REMOTE_URL	—

Inherited agent-utilities variables (apply to every connector)

Variable	Example	Description
MCP_CLIENT_AUTH	—	Outbound MCP child auth: oidc-client-credentials | basic | none
OIDC_CLIENT_ID	—	OIDC client id (service-account auth)
OIDC_CLIENT_SECRET_REF	secret://identity/oidc-client-secret	Runtime secret reference for the OIDC service account
MCP_BASIC_AUTH_USERNAME	—	HTTP Basic username (MCP_CLIENT_AUTH=basic)
MCP_BASIC_AUTH_PASSWORD_REF	secret://identity/mcp-basic-password	Runtime secret reference for HTTP Basic auth (MCP_CLIENT_AUTH=basic)
MCP_URL	http://localhost:8000/mcp	URL of the MCP server the agent connects to
PROVIDER	openai	LLM provider for the agent
MODEL_ID	gpt-4o	Model id for the agent
ENABLE_WEB_UI	True	Serve the AG-UI web interface

28 package + 9 inherited variable(s). Auto-generated from .env.example + the shared agent-utilities set — do not edit.

Every variable the server reads, grouped by concern.

Connection & Credentials

Variable	Purpose	Default
ARIS_API_BASE	ARIS REST base URL (tenant API root)	http://localhost/abs/api
ARIS_SSL_VERIFY	verify TLS	True
ARIS_OAUTH_URL / ARIS_CLIENT_ID / ARIS_CLIENT_SECRET / ARIS_TENANT	OAuth2 client-credentials (preferred)	—
ARIS_TOKEN	static bearer token (alt to OAuth)	—
ARIS_USERNAME / ARIS_PASSWORD	HTTP basic (alt)	—
ARIS_PATHS_JSON	JSON overriding REST path templates per tenant	—
ARIS_ENABLE_WRITE	allow attribute writes	False

Tenant differences. ARIS deployments vary (Connect ABS portal vs the public ARIS API; on-prem vs Cloud). The defaults follow the common ARIS Connect ABS REST layout. If your tenant's paths differ, set ARIS_PATHS_JSON, e.g. {"models":"v2/repository/models","model_objects":"v2/models/{model_id}/objects"}.

MCP server / transport

Variable	Description	Default
TRANSPORT	stdio, streamable-http, or sse	stdio
HOST	Bind host (HTTP transports)	0.0.0.0
PORT	Bind port (HTTP transports)	8000
MCP_TOOL_MODE	Tool surface: condensed, verbose, or both	condensed
MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS	Comma-separated tool allow/deny list	—
MCP_ENABLED_TAGS / MCP_DISABLED_TAGS	Comma-separated tag allow/deny list	—
DEBUG	Verbose logging	False
PYTHONUNBUFFERED	Unbuffered stdout (recommended in containers)	1

Tool toggles

The action-routed tools can be disabled via their toggle env var (set to false): ARISTOOL (see the Available MCP Tools table above).

Telemetry & governance

Variable	Description	Default
ENABLE_OTEL	Enable OpenTelemetry export	True
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint	—
OTEL_EXPORTER_OTLP_PUBLIC_KEY / OTEL_EXPORTER_OTLP_SECRET_KEY	OTLP auth keys	—
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol (e.g. http/protobuf)	—
EUNOMIA_TYPE	Authorization mode: none, embedded, remote	none
EUNOMIA_POLICY_FILE	Embedded policy file	mcp_policies.json
EUNOMIA_REMOTE_URL	Remote Eunomia server URL	—

Agent CLI (full [agent] runtime only)

Variable	Description	Default
MCP_URL	URL of the MCP server the agent connects to	http://localhost:8000/mcp
PROVIDER	LLM provider (e.g. openai)	openai
MODEL_ID	Model id (e.g. gpt-4o)	gpt-4o
ENABLE_WEB_UI	Serve the AG-UI web interface	True

Installation

Install the slim [mcp] extra. Install aris-mcp[mcp] — the MCP-server extra that pulls only the FastMCP / FastAPI tooling (agent-utilities[mcp]). It deliberately excludes the heavy agent runtime (the epistemic-graph engine, pydantic-ai, dspy, llama-index, tree-sitter), so uvx/container installs are dramatically smaller and faster. Use the full [agent] extra only when you need the integrated Pydantic AI agent.

Pick the extra that matches what you want to run:

Extra	Installs	Use when
aris-mcp[mcp]	Slim MCP server only (agent-utilities[mcp] — FastMCP/FastAPI)	You only run the MCP server (smallest install / image)
aris-mcp[agent]	Full agent runtime (agent-utilities[agent,logfire] — Pydantic AI + the epistemic-graph engine)	You run the integrated agent
aris-mcp[all]	Everything (mcp + agent + logfire)	Development / both surfaces

# MCP server only (recommended for tool hosting — slim deps)
uv pip install "aris-mcp[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "aris-mcp[agent]"

# Everything (development)
uv pip install "aris-mcp[all]"      # or: python -m pip install "aris-mcp[all]"

Container images (:mcp vs :agent)

One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:

Image tag	Build target	Contents	Entrypoint
knucklessg1/aris-mcp:mcp	--target mcp	aris-mcp[mcp] — slim, no engine/pydantic-ai/dspy/llama-index/tree-sitter	aris-mcp
knucklessg1/aris-mcp:1.1.0	--target agent (default)	aris-mcp[agent] — full agent runtime + epistemic-graph engine	aris-agent

docker build --target mcp   -t knucklessg1/aris-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/aris-mcp:1.1.0 docker/   # full agent

docker/mcp.compose.yml runs the slim :mcp server; docker/agent.compose.yml runs the agent (:1.1.0) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

The full agent ([agent] / :1.1.0) embeds the epistemic-graph engine (pulled in transitively via agent-utilities[agent]). For production — or to share one knowledge graph across multiple agents — run epistemic-graph as its own database container and point the agent at it instead of embedding it. Deployment recipes (single-node + Raft HA), connection config, and the full database architecture (with diagrams) are documented in the epistemic-graph deployment guide. The slim [mcp] server does not require the database.

Run

aris-mcp                       # stdio (default)
aris-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Deployment

1. stdio — uv run aris-mcp (see mcp_config.json).
2. streamable-http — aris-mcp --transport streamable-http --port 8000.
3. local container — build from docker/ and run with the env above.
4. remote — point your client at https://aris-mcp.example.invalid/mcp.

Deploy with agent-os-genesis

This package can be provisioned for you — skill-guided — by the agent-os-genesis universal skill (its single-package deploy mode): it picks your install method, seeds secrets to OpenBao/Vault (or .env), trusts your enterprise CA, registers the MCP server, and verifies it — the same machinery that stands up the whole Agent OS, narrowed to just this package. Ask your agent to "deploy aris-mcp with agent-os-genesis".

Install mode	Command
Bare-metal, prod (PyPI)	uvx aris-mcp · or uv tool install aris-mcp
Bare-metal, dev (editable)	uv pip install -e ".[all]" · or pip install -e ".[all]"
Container, prod	deploy knucklessg1/aris-mcp:1.1.0 via docker-compose / swarm / podman / podman-compose / kubernetes
Container, dev (editable)	deploy docker/compose.dev.yml (source-mounted at /src; edits live on restart)

Secrets are read-existing + seeded via vault_sync — you are only prompted for what's missing.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, GraphOS delegation, or trace export.