Tools

CALM Hub — MCP & API Reference

⏱ 5 min readOpen CALM Hub ↗Edit on GitHub ↗

CALM Hub exposes two API surfaces:

REST API - the primary interface, fully documented via OpenAPI/Swagger UI.
MCP server - an experimental Model Context Protocol endpoint for AI-agent integrations.

REST API

OpenAPI Specification

CALM Hub uses SmallRye OpenAPI (Quarkus extension) to auto-generate an OpenAPI 3 specification from the JAX-RS resource annotations. The spec reflects the live configuration of the running instance (all endpoints, request/response schemas, security scopes).

Endpoint	Description
`/q/openapi`	OpenAPI 3 specification (YAML)
`/q/openapi?format=json`	OpenAPI 3 specification (JSON)
`/q/swagger-ui`	Interactive Swagger UI explorer

The Swagger UI is always included in the image (quarkus.swagger-ui.always-include=true), so it is available in production as well as development.

Base URL

CALM Hub exposes two REST surfaces:

Numeric-id storage API — /api/calm/...

The primary CRUD interface for namespaces, architectures, patterns, flows, standards, and other artefacts. Resources are addressed by server-assigned numeric IDs.

GET    /api/calm/namespaces
POST   /api/calm/namespaces
GET    /api/calm/namespaces/{namespace}/architectures
POST   /api/calm/namespaces/{namespace}/architectures
GET    /api/calm/namespaces/{namespace}/architectures/{id}/versions/{version}

Name-based API — /calm/...

A user-facing layer that maps human-readable names (slugs) to their numeric IDs and provides versioned access by name. All paths include a /versions/ segment.

POST /calm/namespaces/{namespace}/architectures/{name}/versions/{version}
GET  /calm/namespaces/{namespace}/architectures/{name}/versions
GET  /calm/namespaces/{namespace}/architectures/{name}/versions/{version}
GET  /calm/namespaces/{namespace}/architectures

The type segment is not case-sensitive in a request, so Architectures and architectures name the same resource. This also applies to the type segment in a $id that you send. CALM Hub always writes the type segment in lowercase, in the $id of a returned document and in the Location header. The CALM CLI reads only the lowercase form.

The full endpoint list with request/response schemas is visible in the Swagger UI at /q/swagger-ui.

Finding the architectures that implement a pattern

GET /calm/namespaces/{namespace}/patterns/{name}/versions/{version}/implementations

Use this before you change a pattern. It shows which architectures depend on the version you are about to change.

{
  "pattern": { "namespace": "finos", "name": "api-gateway", "version": "1.0.0" },
  "implementations": [
    { "namespace": "finos", "architectureId": 7, "version": "1.2.0", "customId": "trade-capture" }
  ]
}

An architecture names its pattern in its own $schema, which calm generate sets to the pattern's $id.


Version	A release such as `1.0.0`, or a snapshot such as `1.0.0-SNAPSHOT`. A version that does not exist returns `404`, not an empty list.
Host	Only the path of the `$schema` is compared, so references keep working after the hub moves.
Order	Sorted by namespace, then `architectureId`, then architecture version, so `1.2.0` comes before `1.10.0`.
Paging	`limit` and `offset` are optional. Omit them and you get every match — the endpoint never shortens a list you did not ask to shorten. An `offset` without a `limit` returns every match after the offset.
`customId`	The name on the name-based API. Omitted for an architecture created through the numeric-id API, which never had one; use `architectureId` for those.
GitHub mode	Not available. The endpoint returns `501`.

The hub answers on demand and caches nothing, reading the architectures you are allowed to see. See ADR 0008 for why the link is resolved at request time rather than stored.

Snapshot Versions

A version ending in -SNAPSHOT (e.g. 1.0.0-SNAPSHOT) is mutable — it can be re-posted with new content. A release version (e.g. 1.0.0) is immutable once created. Publishing a release deletes the matching snapshot, if one exists. Snapshots are supported on architectures, patterns, flows, standards, and interfaces only.

Request	Effect	Status
`POST .../versions/1.0.0-SNAPSHOT` (first time)	Creates the snapshot	`201`
`POST .../versions/1.0.0-SNAPSHOT` (again)	Replaces the snapshot's content	`200`
`POST .../versions/1.0.0`	Publishes the release, deletes `1.0.0-SNAPSHOT`	`201`

A snapshot cannot be created if its release version is already published — CALM Hub returns 409 Conflict.

Snapshots are written through the name-based /calm/... API only. The numeric /api/calm/... write endpoints reject a -SNAPSHOT version; their GET endpoints can read one.

Access Control

Endpoints are protected by per-namespace permissions. Access is granted via UserAccess records stored in the active backend; each record ties a username to a permission level for a specific namespace or control domain.

Permission	Scope	What it grants
`read`	namespace	Read artefacts in a namespace
`write`	namespace	Read + write artefacts (implies `read`)
`admin`	namespace	Read + write + manage access grants (implies `write`)
`domain_read`	control domain	Read controls in a domain
`domain_write`	control domain	Write controls in a domain
`global_admin`	all namespaces	Bypasses all namespace permission checks (`admin` on the reserved `GLOBAL` namespace)

Namespace permissions follow a hierarchical model using . as a separator (org, org.team, org.team.project). read is AND-ed across the ancestor chain (every level must have a matching grant); write and admin cascade from any ancestor via OR. See calm-hub/PERMISSIONS.md and the entitlements guide for the full model.

When running without the secure Quarkus profile, authentication is disabled and all endpoints are accessible without a token.

MCP Server

Experimental

The MCP server is disabled by default and is currently experimental. The API surface may change between releases.

What Is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI language models to external tools and data sources. CALM Hub's MCP server exposes its artefact store as a set of callable tools that an LLM can invoke to query architectures, patterns, controls, and more.

Enabling the MCP Server

# application.properties  (or pass as env var)
calm.mcp.enabled=true

# Via environment variable
export CALM_MCP_ENABLED=true
../mvnw quarkus:dev

The MCP endpoint is always registered at /mcp (HTTP Streamable transport). The calm.mcp.enabled flag gates whether the tool handlers are active — with it set to false the endpoint is reachable but all tool calls return a disabled response.

Endpoint

POST /mcp
Content-Type: application/json

CALM Hub uses the HTTP Streamable MCP transport (Quarkiverse quarkus-mcp-server-http, version 1.12.1). This transport uses JSON-RPC 2.0 over HTTP POST.

Available Tools

Tool provider	Example tools
`ArchitectureTools`	`list_architectures`, `get_architecture`
`PatternTools`	`list_patterns`, `get_pattern`
`ControlTools`	`list_controls`, `get_control`
`DomainTools`	`list_domains`, `create_domain`
`InterfaceTools`	`list_interfaces`, `get_interface`
`NamespaceTools`	`list_namespaces`, `create_namespace`
`SearchTools`	`search_architectures`
`StandardTools`	`list_standards`
`TimelineTools`	`get_timeline`
`AdrTools`	`list_adrs`, `get_adr`

To retrieve the full tool list from a running instance:

curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq '.result.tools[].name'

Example Tool Call

# List all namespaces via MCP
curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_namespaces",
      "arguments": {}
    }
  }'

Testing with Quarkus Dev UI

When running in quarkus:dev mode with %dev.quarkus.mcp.server.traffic-logging=true, all JSON-RPC messages are printed to the console. The Quarkus Dev UI also ships an interactive MCP tester.

Connecting an AI Client

Any MCP-compatible AI client (e.g. Claude Desktop, Cursor, VS Code with an MCP extension) can connect to CALM Hub by adding it as an HTTP MCP server pointing at http://<host>:8080/mcp.

Example mcp.json entry for Claude Desktop or a compatible client:

{
  "mcpServers": {
    "calm-hub": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

REST API​

OpenAPI Specification​

Base URL​

Finding the architectures that implement a pattern​

Snapshot Versions​

Access Control​

MCP Server​

What Is MCP?​

Enabling the MCP Server​

Endpoint​

Available Tools​

Example Tool Call​

Testing with Quarkus Dev UI​

Connecting an AI Client​

Further Reading​