Tools

CALM Hub — MCP & API Reference

⏱ 3 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 full endpoint list with request/response schemas is visible in the Swagger UI at /q/swagger-ui.

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​

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​