orionbelt-semantic-layer-mcp

<!-- mcp-name: io.github.ralforion/orionbelt-semantic-layer-mcp --> <p align="center"> <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer-mcp/main/docs/assets/ORIONBELT_Logo.png" alt="OrionBelt® Logo" width="400"> </p> <h1 align="center">OrionBelt® Semantic Layer MCP</h1> <p align="center"><strong>Thin MCP server that delegates to the OrionBelt® Semantic Layer REST API</strong></p>

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

The OrionBelt® Semantic Layer platform has two deployment modes. This MCP server supports both:

• Standalone — Deploy the OrionBelt® Semantic Layer API anywhere (Cloud Run, Docker, localhost) and point this MCP server at it via API_BASE_URL.
• Hosted — Connect to the public Cloud Run deployment with zero local setup (see Hosted MCP Server below).

┌────────────┐       ┌──────────────────────────────────────────────────────┐
│ LLM Client │       │                OrionBelt® Platform                   │
│            │       │                                                      │
│  Claude,   │──MCP──│──> server.py  ──HTTP /v1──>  Semantic Layer REST API │
│  Cursor,   │       │    (FastMCP                   (FastAPI: parse OBML,  │
│  any MCP   │       │     + httpx)                   validate, compile     │
│  client    │       │                                to SQL)               │
└────────────┘       └──────────────────────────────────────────────────────┘

• No business logic — all tool calls delegate to the REST API (v1 endpoints)
• Dual-mode — auto-detects single-model or multi-model API mode at startup
• Auto-session management — creates an API session on first tool call, caches the ID (multi-model mode)
• 24 tools (single-model mode) or 28 tools (multi-model mode) for querying (QueryObject), execution, batch, discovery, composability (ACR), examples, diagrams, RDF/SPARQL, business rules (list, explain, evaluate), ontology links (concept mappings, namespaces, unmapped artefacts), OSI export, model validation (offline or against the live datasource), and OBML reference + function catalog + JSON schemas. (29 distinct tools exist in total; the API mode selects which subset is active — they overlap in 23 — and no client ever sees all 29 at once.) The visible surface is narrowed further in the design-time phase and when query execution is disabled (see Design-time vs run-time tool switching)
• 5 prompts + 2 resources for OBML / OBSQL reference, business rules, and usage guidance

<p align="center"> <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer-mcp/main/docs/assets/architecture.png" alt="OrionBelt® Analytics Architecture" width="900"> </p>

Live Demo

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

API endpoint: https://orionbelt.ralforion.com — Swagger UI | ReDoc | Gradio UI

Set API_BASE_URL=https://orionbelt.ralforion.com 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

The HTTP transport runs stateless by default (MCP_STATELESS_HTTP=true): every request is self-contained, with no Mcp-Session-Id, no stream resumability, and no server-initiated messages. Nothing here needs that state — the tool phase is derived from explicit loaded-model state rather than from the connection, and no tool sends progress, sampling, or elicitation requests — so instances can sit behind a load balancer without session affinity. Set MCP_STATELESS_HTTP=false to restore per-connection sessions; sse always runs stateful, since it is a long-lived per-connection stream.

Note this is the transport session only. The upstream API session and the set of loaded models remain process-global and shared by every client of an instance, unchanged by this flag.

Transport security

The HTTP/SSE transport terminates no TLS and authenticates no caller — it expects an ingress in front that does both. These are two separate jobs, and no platform does both for you by default.

On Cloud Run, the intended deployment, TLS is automatic: the service URL is served over HTTPS and plain HTTP is forwarded to the container. Access control is not. It is a deploy-time choice, settled any of three ways — IAM invoker permission, an --ingress restriction, or an authenticating load balancer in front. With none of them, --allow-unauthenticated leaves the service reachable by anyone who learns its URL, over HTTPS, with no credential required. Encrypted is not the same as restricted.

This matters because the two hops have different answers:

| Hop | Security | | --- | --- | | MCP client → this server | stdio: pipes to a child process, no socket at all. http/sse: whatever the ingress in front provides — nothing if there is none | | This server → the API | TLS whenever API_BASE_URL is https:// (the default), with certificates verified against httpx's default CA bundle (certifi), or against API_CA_CERT for a private CA; API_CLIENT_CERT adds a client certificate for mutual TLS. There is no verify=False and no way to disable it short of an http:// URL |

Exposing the HTTP transport directly is the case to avoid. Anything that can reach the port can call every registered tool — including execute_query where the capability is enabled — spending this server's own API_KEY against the API, over a channel readable in transit. The credential never crosses that hop; the access it buys does.

The server warns at startup when it detects this: an http/sse transport bound to a non-loopback address, off Cloud Run, without MCP_BEHIND_PROXY=true. Bind MCP_SERVER_HOST to loopback, put an authenticating TLS ingress in front, or set MCP_BEHIND_PROXY=true to acknowledge a proxy the server has no way to see.

On Cloud Run it logs an informational note instead of that warning, naming the half that is still yours: TLS is handled, access control is whatever you deployed with. Silence there is not evidence the service is restricted — the process cannot read its own IAM policy or ingress setting. Confirm one of the three above is in place; if one is, MCP_BEHIND_PROXY=true records that and silences the note.

The API's own *_TLS_* settings are the server half and none of them is read here. PGWIRE_TLS_* and FLIGHT_TLS_* (2.28.0) secure listeners this server never connects to. API_TLS_* (2.29.0) makes the REST API serve HTTPS itself, and API_TLS_CLIENT_CA makes it require a client certificate — which is what the settings below are for.

TLS to the API

When the API serves HTTPS with a certificate from a private CA, or requires mutual TLS — API_TLS_CLIENT_CA on the API, or a gateway in front that asks for a client certificate — point this server at the material:

API_BASE_URL=https://obsl.internal:8000
API_CA_CERT=/certs/ca.crt            # trust this CA instead of the default store
API_CLIENT_CERT=/certs/mcp.crt       # present this certificate…
API_CLIENT_KEY=/certs/mcp.key        # …with this key (omit if it is in the same PEM)

The certificate is loaded when the server starts, on every transport, so a path that is missing, unreadable, or not what it claims stops startup naming the setting and the file — rather than surfacing later as an SSL error from inside the HTTP client. The startup banner's API TLS: line reports what the hop ended up with.

• API_CA_CERT replaces the default trust store, it does not extend it. Unset, verification uses httpx's default (certifi, or SSL_CERT_FILE / SSL_CERT_DIR), and adding a client certificate does not change that.
• These require an https:// API_BASE_URL. On http:// there is no handshake, so nothing would be presented or verified; that configuration is refused rather than left to read as TLS.
• Password-protected keys are refused, not prompted for. Under stdio, stdin is the MCP pipe, so OpenSSL's terminal prompt would corrupt the protocol or hang. Provide the key decrypted, protected by file permissions or a secret mount.

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 | | API_KEY | — (unset) | API credential; required only when the API runs with `AUTH_MODE=api_