orionbelt-semantic-layer-mcp 0.7.0

Thin MCP server for OrionBelt Semantic Layer — delegates to REST API

OrionBelt Semantic Layer MCP

Thin MCP server that delegates to the OrionBelt Semantic Layer REST API

A thin MCP server that delegates all business logic to the OrionBelt Semantic Layer REST API via HTTP. No embedded engine — pure API pass-through.

Architecture

LLM Client  ──MCP──>  server.py  ──HTTP──>  OrionBelt Semantic Layer API
                       (FastMCP + httpx)     (Cloud Run / localhost)

• No business logic — all tool calls delegate to the REST API
• Auto-session management — creates an API session on first tool call, caches the ID
• 10 tools for model loading, validation, querying, diagrams, and format conversion
• 3 prompts + 1 resource for OBML reference and usage guidance

Live Demo

A public demo of the OrionBelt Semantic Layer API is available at:

API endpoint: http://35.187.174.102 — Swagger UI | ReDoc | Gradio UI

Set API_BASE_URL=http://35.187.174.102 in your .env file to use it (see .env.example).

Installation

uv sync

For development (includes pytest, respx, ruff):

uv sync --all-groups

Usage

stdio (default)

uv run server.py

HTTP transport

MCP_TRANSPORT=http uv run python server.py

MCP client configuration

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "orionbelt": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/orionbelt-semantic-layer-mcp"
    }
  }
}

Configuration

Environment variables or .env file (pydantic-settings). See .env.example for defaults.

Variable	Default	Description
API_BASE_URL	— (required)	OrionBelt Semantic Layer REST API URL
MCP_TRANSPORT	stdio	stdio, http, or sse
MCP_SERVER_HOST	localhost	Bind host for HTTP/SSE
MCP_SERVER_PORT	9000	Bind port for HTTP/SSE
LOG_LEVEL	INFO	Logging level
API_TIMEOUT	30	HTTP timeout in seconds

Tools

MCP Tool	Description
get_obml_reference()	Returns the full OBML format specification
load_model(model_yaml)	Parse, validate, and store a semantic model
validate_model(model_yaml)	Validate a model without storing it
describe_model(model_id)	Inspect data objects, dimensions, measures, metrics
compile_query(...)	Compile a semantic query to SQL (simple + full mode)
list_models()	List all models loaded in the current session
list_dialects()	List available SQL dialects and capabilities
get_model_diagram(model_id)	Generate a Mermaid ER diagram for a loaded model
convert_osi_to_obml(input_yaml)	Convert OSI YAML to OBML format
convert_obml_to_osi(input_yaml)	Convert OBML YAML to OSI format

Supported SQL Dialects

postgres, snowflake, clickhouse, databricks, dremio

Workflow

1. Get reference — call get_obml_reference() to learn OBML syntax
2. Load model — call load_model(model_yaml) to get a model_id
3. Explore — call describe_model(model_id) to inspect the model
4. Query — call compile_query(model_id, dimensions=[...], measures=[...]) to generate SQL

Development

# Run tests
uv run pytest

# Lint
uv run ruff check server.py
uv run ruff format server.py tests/

MCP Live Demo Hosting at Prefect Horizon

The OrionBelt Semantic Layer MCP server is available as a hosted live demo on Prefect Horizon, a managed platform for deploying MCP servers.

Quick start with Claude Desktop

1. Download the Desktop Extension: orionbelt-semantic-layer.dxt
2. Open the .dxt file in Claude Desktop (requires Claude Desktop with MCP support)

No local setup or API key needed — the hosted server connects to the live demo API.

License

Copyright 2025 RALFORION d.o.o.

Licensed under the Apache License, Version 2.0. See LICENSE for details.

---