Semalith MCP server
Commit Nov 7, 2026Provides a semantic layer between business data and AI agents using a lean ontology and knowledge base to improve query accuracy and cost.
Also known as rosetta-oss/semalith-runtime
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- —
What is Semalith MCP?
Semalith provides a semantic layer between business data and AI agents using a lean ontology and knowledge base to improve query accuracy and cost.
Summary generated from the project's README
About Semalith MCP server
Providing business meaning to AI agents through a lean ontology is what semalith-runtime enables. It acts as a semantic layer that sits between your existing databases or APIs and your AI clients, such as Claude Code or Codex. Instead of forcing agents to navigate raw tables, this runtime uses a knowledge base and a structured graph of entities, relationships, and rules to ensure queries are accurate and cost-effective.
Developers deploy the runtime using Docker and Compose, which can include a sample ERP for testing. The system provides two distinct MCP servers: a data-plane server for querying the graph and a builder server for creating or modifying the ontology. Users connect their clients using specific JSON configurations and must trust a self-signed certificate provided during setup. By using 12 fixed MCP tools, the server allows agents to perform complex tasks like multi-source queries and governed writes without requiring constant changes to the underlying toolset.
What you can do with it
- 1Execute complex business queriesAsk an AI agent to calculate total purchasing bills or compare sales trends across different years.
- 2Automate graph developmentUse an AI agent to build and test a new business ontology by setting goals and golden cases.
- 3Enforce business rules and securityEnsure that AI agents respect specific organizational rules and row-level security defined in the ontology.
- 4Reduce AI operational costsLower the expense of running agentic workflows by providing a semantic layer instead of a plain REST API.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
NODE_EXTRA_CA_CERTSSEMALITH_GRAPH_TOKEN
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerosetta-oss/semalith-runtime is public and reachablegithub.com/rosetta-oss/semalith-runtime ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-07github.com/rosetta-oss/semalith-runtime ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSemalith
The semantic layer between your data and AI agents.
Watch the 2-minute video: the graph behind an agentic ERP. Subtitles
Semalith gives AI agents your business meaning, not just your tables. You describe the business once as a lean ontology (entities, relationships, metrics, rules and actions) with a knowledge base beside it, and agents query it over MCP. Answers come with their definitions and limits stated.
Against a plain REST API on the same ERP, the same AI agent was 2.6 times cheaper, 37% faster and more accurate, with the largest gain on questions that need business rules.
This repository holds the runtime as Docker images, a one-command demo on a sample ERP, and our benchmark. It contains no source code.
Benchmark

An AI agent answered 44 business questions about the demo ERP, three times each, through three paths: a plain REST API, the Semalith graph, and the graph with its knowledge base.
| Path | Cost | Time per answer | Accuracy | Rule-based questions | Overall |
|---|---|---|---|---|---|
| Plain REST | $35.23 | 29.8 s | 0.874 | 0.818 | 83.0 |
| Graph | $13.07 | 19.1 s | 0.916 | 0.833 | 91.9 |
| Graph + knowledge | $13.34 | 18.9 s | 0.956 | 0.919 | 92.9 |
The cost and speed gains repeated in every round. The results depend on the REST design, the data and the model, and the scores were set by AI. Read the report for the method, the limits and the questions.
Why Semalith
- Goal-driven graph development. You set the goal and the golden cases. An AI agent such as Claude or Codex builds the graph over MCP, tests it against the cases, and improves it until they pass.
- Enforce what must hold, explain what must be understood. Rules, row security and actions live in the ontology and are enforced. Business context that rows can't state lives in a reviewed knowledge base.
- Light to start. No data migration and no platform: Semalith reads and acts on your existing databases and APIs.
- High ceiling. One contract covers multi-source queries, unions, recursion, derived metrics and governed writes.
- Released like software. Every release is validated, sealed and reversible.
- Standard tools. Agents use 12 fixed MCP tools. New business needs change the graph, not the tools.
What it looks like
These screens come from the ERP demo graph.
Explorer. The whole model as a graph: 41 entities, 450 attributes and 59 resolvers, with each entity's definition and identity.

Knowledge. Reviewed articles that explain what the data can't, linked to the entities they apply to.

Publish. Quality checks, sealed versions you can roll back to, the MCP address and access tokens.

Usage. Requests, failure rate and latency, and where agents get stuck, so you know what to improve next.

Quick start
You need Docker with Compose v2, about 3 GB of memory, and internet access for the first start.
curl -fsSL https://raw.githubusercontent.com/rosetta-oss/semalith-runtime/main/compose.yaml -o compose.yaml
docker compose up -d
The first start downloads Microsoft's AdventureWorks sample, loads a demo ERP, publishes a ready-made graph and creates the demo sign-in. Then:
docker compose logs setup
This prints the Builder address and the sign-in, demo@test.com / semalith-demo. Setup also writes the connection files to ./semalith-connect:
| File | What it is |
|---|---|
mcp-config.json |
The data-plane MCP server for the ERP graph, with its graph token |
builder-mcp-config.json |
The Builder MCP server, for creating and changing graphs, with a 30-day workspace token |
studio.pem |
Studio's self-signed certificate, which your client must trust |
golden-cases.md |
Verified questions to try |
The graph token can only query this graph. The workspace token can change graphs, so keep it private. To issue new tokens, run setup again:
docker compose run --rm setup
Connect an AI client
Claude Code
The script registers both servers and starts Claude Code trusting the certificate:
cd semalith-connect && ./connect-claude.sh
To do it by hand:
cd semalith-connect
claude mcp add-json erp-demo "$(cat mcp-config.json)"
claude mcp add-json erp-builder "$(cat builder-mcp-config.json)"
NODE_EXTRA_CA_CERTS="$PWD/studio.pem" claude
Codex
Put the graph token in an environment variable and register the server:
cd semalith-connect
export SEMALITH_GRAPH_TOKEN="$(python3 -c 'import json; print(json.load(open("mcp-config.json"))["headers"]["Authorization"].split()[-1])')"
codex mcp add erp-demo --url "$(python3 -c 'import json; print(json.load(open("mcp-config.json"))["url"])')" --bearer-token-env-var SEMALITH_GRAPH_TOKEN
The variable must be set in the shell that starts Codex. Codex must also trust studio.pem, for example by adding it to your system's trusted certificates. We have not tested Codex with the demo yet.
Other MCP clients
Use the URL and Authorization header in mcp-config.json, and make the client trust studio.pem.
Try the ERP demo
Ask your agent, for example:
What was our total purchasing bill for 2024, and which month was the heaviest?
Put reseller sales for January to June 2025 next to January to June 2024. Is the channel growing or shrinking?
Which products have we sold since the end of June 2024 that now have no stock and nothing on the way?
More questions with verified answers are in semalith-connect/golden-cases.md. To build or change a graph with AI, use the Builder server (erp-builder) and ask your agent to read the graph, add an entity or saved query, and publish it.
Open the Builder
The Builder is the web interface where you can read the graph, its knowledge and its releases.
- Open https://localhost:9631 in your browser.
- Your browser warns that the certificate is not trusted, because the demo uses a self-signed one. Choose to continue to localhost.
- Sign in as demo@test.com with the password semalith-demo.
- Open the ERP graph: https://localhost:9631/#/graphs/erp/erp-demo. Its tabs show the model, saved queries, knowledge and releases. The Publish tab, https://localhost:9631/#/graphs/erp/erp-demo/publish, lists the published versions.
If you set STUDIO_PORT, use that port instead of 9631.
To remove everything:
docker compose down -v
Limits
- Early software. Expect breaking changes before 1.0.
- The demo uses a self-signed certificate and a fixed sign-in, and listens on this computer only. Do not expose it to a network, and change both before using real data.
- No support commitment.
Licence
Free for demonstration, evaluation (including by an individual inside their organisation) and personal research. Commercial use, production use, offering it as a service, redistribution and reverse engineering need written permission. This is not open-source software; see LICENSE. Third-party notices are in NOTICE and THIRD-PARTY-NOTICES.md. AdventureWorks is MIT-licensed Microsoft sample data, downloaded at install time.
Semalith MCP questions
How does Semalith compare to a plain REST API?
Against a plain REST API, an AI agent using Semalith was 2.6 times cheaper, 37% faster and more accurate.
What is required to run the Semalith demo?
You need Docker with Compose v2, approximately 3 GB of memory, and internet access for the initial setup.
Can Semalith work with my existing data?
Yes, Semalith does not require data migration and can read and act on your existing databases and APIs.
How do I connect an AI client like Claude Code?
You can use the provided connect-claude.sh script or manually add the MCP servers using the configuration files generated during setup.
