Copyright (c) 2025, Software Tree

ORMCP Server - Beta

Last updated: 2026-10-06 (ORMCP 0.7.1)

A Model Context Protocol (MCP) Server to connect your AI applications to relational databases

ORMCP Server enables AI LLMs and MCP clients to easily exchange object-oriented data (in JSON format) with any relational database using the MCP standard protocol.

ORMCP Server makes your relational data AI ready.

⚠️ Beta Notice

ORMCP Server is currently in Beta, and we are offering early access to users who want to check the software, provide feedback, and help us ensure the product meets the highest quality standards. This Beta version is not intended for commercial use, and it is provided for testing purposes only.

Related MCP server: io.github.ralfbecher/orionbelt-analytics

📋 Table of Contents

• What is MCP?

• Features

• How It Works

• Quick Start

• Platform-Specific Guides — 🍎 macOS · 🪟 Windows · 🐧 Linux

• Installation

• Gilhari Microservice Setup

• Configuration

• Starting the Server

• Client Configuration

• Usage Examples

• MCP Tools Reference

• Troubleshooting

• Development

• Contributing

• License

• Support & Resources

What is MCP?

The Model Context Protocol (MCP) is an open standard that provides a unified way for AI models to interact with external tools and data sources. It standardizes communication, making it easier to integrate LLMs into complex workflows without building custom API integrations for every use case.

Learn more at the Official MCP Website.

✨ Features

• ✅ Standardized Interface: Fully compliant with the Model Context Protocol (MCP) specification

• 🌐 Database Agnostic: Works with any JDBC-compliant database (e.g., PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite)

• ↔️ Bi-directional Data Flow: Seamless AI ↔ Database communication with optional support for only READONLY operations

• 🔄 Object-Relational Mapping (ORM): JSON object operations (CRUD) transparently mapped to relational data

• 🔒 Secure Data Access: Domain model-specific operations promote data protection

• 🧾 Declarative ORM Specification: Intuitive, non-intrusive, and flexible ORM specification based on a simple grammar

• 🕸️ Support for Complex Object Modeling: Including one-to-one, one-to-many, and many-to-many relationships, and path-expressions

• 🖇️ Flexible Queries: Deep and Shallow queries, Various operational directives similar to GraphQL capabilities to refine the shape and scope of returned objects

• 🚀 Highly Optimized and Lightweight Mapping Engine: Connection pooling, Prepared statements, Optimized SQL statements, Minimal database trips, Caching of metadata

• 🔌 Compatible with Existing Data and Databases: Works with existing schemas and data in any database; Does not require any native JSON data type

• 📚 Comprehensive Documentation: Detailed User manual and README files, API documentation, sample apps

• ☁️ Cloud Agnostic: Deploy anywhere with Docker support

• ⚡ High Performance: Built on versatile Gilhari microservice architecture and optimised ORM engine

• 🛡️ Robust Error Handling: Clear error messages and recovery mechanisms

• 📈 Scalable: Handles multiple concurrent requests efficiently; Scalable Docker deployment

How It Works

+---------------------+         +----------------------+         +-------------------------+
| AI App / LLM Client | <--->   |     ORMCP Server     | <--->   |   Relational Database   |
| (MCP-compliant tool)|         |    (MCP + Gilhari)   |         | (Postgres, MySQL, etc.) |
+---------------------+         +----------------------+         +-------------------------+
         |                                |                                 |
         |  JSON (via MCP Tools)          |                                 |
         |------------------------------->|                                 |
         |                                |   ORM + JDBC                    |
         |                                |-------------------------------->|
         |                                |                                 |
         |     JSON result (MCP format)   |                                 |
         |<-------------------------------|                                 |

Important: The AI application (LLM client) translates natural language into MCP tool calls. ORMCP Server then translates these MCP tool calls into REST API calls to Gilhari.

ORMCP Server bridges the gap between modern AI applications and relational databases through:

• MCP Protocol: Standardized AI-to-tool communication

• Gilhari: Integration layer with relational databases via ORM and JDBC

• JSON Mapping: Transparent object-relational mapping

🚀 Quick Start

New to ORMCP? Jump straight to your platform-specific guide for a streamlined setup: 🍎 macOS · 🪟 Windows · 🐧 Linux

The sections below cover all platforms together as a complete reference.

Three Simple Steps to Use ORMCP

1. Scope Your Data

• Define lightweight object models for your relevant data

• Write a declarative ORM specification for those models in a text file using a simple (JDX) grammar

2. Build Your Gilhari Microservice

• Add models, ORM specification, and JDBC driver to a Dockerfile

• Build the Gilhari Docker image

3. Run with ORMCP

• Connect ORMCP to the Gilhari microservice

• Start Gilhari, then ORMCP

• Interact with scoped relational data in an intuitive, object-oriented way using an AI Agent or MCP client

Detailed Quick Start

Prerequisites

• Python 3.12+

• Docker (for Gilhari microservice)

• JDBC driver for your target database

1. Install ORMCP Server

Platform-specific guides with step-by-step install instructions for your OS: macOS · Windows · Linux

ORMCP Server is available on public PyPI. No account, token, or beta-access request is needed to install it:

pip install ormcp-server

# Verify installation
pip show ormcp-server

📌 Linux/Mac Users: Modern Linux distributions and macOS may require virtual environments. See your platform guide or the troubleshooting guide if you get "externally-managed-environment" errors.

# Create virtual environment (recommended on Linux/Mac)
python3 -m venv .venv

# Activate — Linux/Mac:
source .venv/bin/activate
# Activate — Windows (Command Prompt):
.venv\Scripts\activate
# Activate — Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Install
pip install ormcp-server

If you have an existing Gemfury token from an earlier beta install, it will no longer work — Gemfury access has been discontinued. Use pip install ormcp-server, which pulls from public PyPI directly.

If ormcp-server command is not found after installation:

Add the Python executable directory to your PATH. See your platform guide for details: macOS · Windows · Linux

2. Set Up Gilhari Microservice

See detailed setup in Gilhari Microservice Setup section below.

Note: A complete working example is available in a separate repository: gilhari_example1

To run the example:

IMPORTANT: Docker is required for building and running a Gilhari microservice — Get Docker if not already installed on your machine

# Clone the example repository of a sample Gilhari microservice that deals with User type of objects
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# Pull Gilhari Docker image
docker pull softwaretree/gilhari:latest

# Build a Docker image for the sample Gilhari microservice
gilhari\build.cmd    # On Windows
# or
./gilhari/build.sh   # On Linux/Mac

# Run the sample microservice
docker run -p 80:8081 gilhari_example1:1.0

# Optionally, populate the database with sample data
gilhari\curlCommandsPopulate.cmd    # On Windows
# or
./gilhari/curlCommandsPopulate.sh   # On Linux/Mac

3. Configure Environment

# Linux/Mac
export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export MCP_SERVER_NAME="MyORMCPServer"

# Windows (Command Prompt)
set GILHARI_BASE_URL=http://localhost:80/gilhari/v1/
set MCP_SERVER_NAME=MyORMCPServer

# Windows (PowerShell)
$env:GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
$env:MCP_SERVER_NAME="MyORMCPServer"

4. Start the ORMCP Server

ormcp-server

If you get command not found errors, see your platform guide: macOS · Windows · Linux

# Or use Python directly (works on all platforms)
python -m ormcp_server

5. Connect Your AI Client

For Claude Desktop, add to claude_desktop_config.json:

Option 1: Using command name (requires PATH configured):

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Option 2: Using full path (recommended for Windows):

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "C:\\Users\\<YourUsername>\\AppData\\Roaming\\Python\\Python313\\Scripts\\ormcp-server.exe",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

To find your exact path:

# Windows (PowerShell)
(Get-Command ormcp-server).Source

# Or use pip
pip show -f ormcp-server | findstr "Location"

# Linux/Mac
which ormcp-server

You're ready! Your AI client can now interact with your database using natural language.

Note: Steps 3 (Configure Environment) and 4 (Start the ORMCP Server) are not necessary if you are using Claude Desktop as a client because Claude Desktop automatically starts a configured ORMCP server in STDIO mode.

Usage Examples

Query Data

AI Prompt: "Show me all users with age greater than or equal to 55"

Generated MCP Call:

{
  "name": "query",
  "arguments": {
    "className": "User",
    "filter": "age >= 55",
    "maxObjects": -1,
    "deep": true
  }
}

Result:

[
  {"id": 55, "name": "Mary55", "city": "Campbell", "state": "CA"},
  {"id": 56, "name": "Mike56", "city": "Boston", "state": "MA"}
]

Insert Data

Note: insert (like the other data-modification tools) is only exposed when READONLY_MODE=False is set — see Configuration for ORMCP Server. With the default READONLY_MODE=True, this example's MCP call won't be available to the client.

AI Prompt: "Add a new User (id = 65) named John Smith of Boston, MA with age of 65"

Generated MCP Call:

{
  "name": "insert",
  "arguments": {
    "className": "User",
    "jsonObjects": [
      {
        "id": 65,
        "name": "John Smith",
        "city": "Boston",
        "state": "MA",
        "age": 65
      }
    ]
  }
}

Aggregate Data

AI Prompt: "What's the average age of users in California?"

Generated MCP Call:

{
  "name": "getAggregate",
  "arguments": {
    "className": "User",
    "attributeName": "age",
    "aggregateType": "AVG",
    "filter": "state='CA'"
  }
}

Result:

49

Gilhari Microservice Setup

ORMCP Server depends on Gilhari software, a microservice framework for JSON data integration with databases. This setup must be completed before starting the ORMCP server.

IMPORTANT: Docker is required for building and running a Gilhari microservice — Get Docker if not already installed on your machine

Install Gilhari Software

1. Pull the Gilhari Docker image:

   docker pull softwaretree/gilhari:latest

2. Install the Gilhari SDK:

   • The SDK for Gilhari software is bundled in the ORMCP Server package under the Gilhari_SDK folder

   • Alternatively, download from: https://www.softwaretree.com/v1/products/gilhari/download-gilhari.php

   • The SDK includes documentation (READMEs, API guides, sample applications) to help you use Gilhari software easily

Configure Your App-Specific Gilhari Microservice

Follow these steps (detailed in Gilhari SDK documentation):

1. Define domain model classes - Java container classes for your JSON objects

2. Create declarative ORM specification - Map JSON attributes to database schema

3. Build Docker image of the app-specific Gilhari microservice - Include domain classes, ORM specification, and JDBC driver

4. Run the microservice:

   docker run -p 80:8081 your-gilhari-service:1.0

Note: A complete working example is available in a separate repository: gilhari_example1. This example demonstrates a Gilhari microservice that manages User objects.

Quick Start with Example:

# Clone the example repository
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# Build a Docker image for the sample Gilhari microservice
gilhari\build.cmd    # On Windows
# or
./gilhari/build.sh   # On Linux/Mac

# Run the sample microservice
docker run -p 80:8081 gilhari_example1:1.0

# Optionally, populate the database with sample data
gilhari\curlCommandsPopulate.cmd    # On Windows
# or
./gilhari/curlCommandsPopulate.sh   # On Linux/Mac

For detailed setup and configuration instructions, see the gilhari_example1 README.

ORMCP Package Installation

Recommended: Virtual Environment

# Create and activate virtual environment
python -m venv .venv

# Activate the environment
# Linux/Mac:
source .venv/bin/activate
# Windows (Command Prompt):
.venv\Scripts\activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Install ORMCP Server from public PyPI — no token needed
pip install ormcp-server

Global Installation

pip install ormcp-server

Note: When installing globally (without a virtual environment), the ormcp-server executable will be installed to your user's Python Scripts directory. See your platform guide if you encounter "command not found" errors.

Accessing Full Package with SDK and Examples

To access the complete package including Gilhari SDK, examples, and documentation:

# Download source distribution
pip download --no-binary :all: ormcp-server

# Extract it (use the appropriate version number)
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# Now you have access to:
# - Gilhari_SDK/          (Complete SDK with documentation)
# - gilhari_example1/     (Ready-to-use example microservice)
# - package/client/       (Example client code)
# - package/docs/         (Additional documentation)

Windows users: If you don't have tar installed, you can:

• Use 7-Zip or WinRAR to extract the .tar.gz file

• Or use PowerShell: tar -xzf ormcp_server-*.tar.gz

• Or download directly from the PyPI project page

Package Contents

The ORMCP Server package includes additional resources beyond the Python code:

Runtime Installation (Wheel)

When you install via pip, you get the core Python package needed to run ORMCP Server:

pip install ormcp-server

This installs only the essential runtime files to your Python environment.

Full Package with SDK and Documentation (Source Distribution)

The complete package includes:

• Gilhari_SDK/ - Complete SDK with documentation, examples, and tools for creating custom Gilhari microservices

• gilhari_example1/ - Ready-to-use example Gilhari microservice

• package/client/ - Example client code and usage documentation

• package/docs/ - Additional technical documentation

• pyproject.toml - Build configuration

• README.md - This file

• LICENSE - License terms

Accessing the Full Package

Option 1: Download from PyPI

# Download the source distribution (.tar.gz)
pip download --no-binary :all: ormcp-server

# Extract it (use the appropriate version number; e.g., 0.7.x)
tar -xzf ormcp_server-0.7.x.tar.gz
cd ormcp_server-0.7.x

# Now you have access to:
# - Gilhari_SDK/
# - gilhari_example1/
# - package/client/
# - package/docs/

Windows users: If you don't have tar installed, you can:

• Use 7-Zip or WinRAR to extract the .tar.gz file

• Or use PowerShell: tar -xzf ormcp_server-0.7.x.tar.gz

• Or download directly from the PyPI project page

Option 2: Download from Package Page

Visit https://pypi.org/project/ormcp-server/ and download the .tar.gz file.

Look for the "Download files" section and download the source distribution (.tar.gz).

Using the Gilhari SDK

After extracting the source distribution:

# Navigate to the SDK
cd Gilhari_SDK

# Read the documentation
# - Check README files for setup instructions
# - Review examples in the examples/ directory
# - See API documentation for ORM specification details

# The SDK includes:
# - Gilhari Docker base image information
# - Documentation (READMEs, API guides)
# - Sample applications
# - Tools for reverse-engineering ORM from existing databases
# - JDX grammar specification

Running the Example Gilhari Microservice

# Navigate to the example
cd gilhari_example1

# Follow the README.md in that directory to:
# 1. Build the Docker image
# 2. Run the microservice
# 3. Populate sample data
# 4. Test with ORMCP Server

Why Two Package Formats?

• Wheel (.whl) - Binary distribution, fast to install, includes only runtime code (~50KB)

• Source Distribution (.tar.gz) - Complete package with all resources (~several MB)

Most users only need the wheel for running ORMCP Server. Download the source distribution if you need:

• The Gilhari SDK for creating custom microservices

• Example applications and client code

• Complete documentation

• Additional technical guides

Configuration for ORMCP Server

Configure via environment variables:

Notes:

• READONLY_MODE defaults to True: the MCP tools that can potentially modify data (insert, update, update2, delete, delete2) are not exposed by the ORMCP server to the MCP client unless you explicitly set READONLY_MODE=False.

• At start-up, ORMCP checks that the Gilhari microservice answers at GILHARI_BASE_URL — the same address it then sends all its requests to. Since ORMCP 0.7.0, the host and port for this check come from GILHARI_BASE_URL, so GILHARI_BASE_URL alone is enough; GILHARI_HOST and GILHARI_PORT only override it, and ORMCP warns if they differ from GILHARI_BASE_URL.

• If no microservice answers, ORMCP can start one itself: set GILHARI_IMAGE (and optionally GILHARI_NAME); the container's host port is the port in GILHARI_BASE_URL (or GILHARI_PORT). If the check still fails, ORMCP stops with a message naming the address it checked and what to do next.

• ORMCP_LOG_FILE: the file rotates at 5 MB, keeping two older copies. If it cannot be written, ORMCP logs a warning and continues with console logging. In a Windows shell, set ORMCP_LOG_FILE= removes the variable (default file); use none to turn file logging off.

• HOST_ORIGIN_PROTECTION accepts true/1/yes/on/strict and false/0/no/off; any other value, including auto, keeps the protection on and logs a warning. ALLOWED_HOSTS/ALLOWED_ORIGINS apply only while the protection is on.

Configuration Example

# Linux/Mac
export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export GILHARI_TIMEOUT="30"
export MCP_SERVER_NAME="MyORMCPServer"
export LOG_LEVEL="INFO"

# Windows (Command Prompt)
set GILHARI_BASE_URL=http://localhost:80/gilhari/v1/
set GILHARI_TIMEOUT=30
set MCP_SERVER_NAME=MyORMCPServer
set LOG_LEVEL=INFO

# Windows (PowerShell)
$env:GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
$env:GILHARI_TIMEOUT="30"
$env:MCP_SERVER_NAME="MyORMCPServer"
$env:LOG_LEVEL="INFO"

Starting the Server

Standard Mode (Recommended)

Activate your virtual environment (if using one):

# Linux/Mac
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Start the server using the CLI command:

ormcp-server

This runs the MCP server in stdio mode via the main.py entry point.

Troubleshooting — Command Not Found:

If you get 'ormcp-server' is not recognized or command not found, see your platform guide for PATH configuration and fix options: macOS · Windows · Linux

# Use Python directly on any platform (always works)
python -m ormcp_server

Using Source Code Directly (Advanced)

Note: Requires source distribution. Download with:

pip download --no-binary :all: ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

Run the server directly with Python:

python src/ormcp_server.py

This bypasses the CLI wrapper and runs the server directly.

Alternative Methods (Advanced Users)

Direct executable execution:

# Windows
.venv\Scripts\ormcp-server.exe

# Linux/Mac
.venv/bin/ormcp-server

Using fastmcp CLI (requires source distribution):

fastmcp run src/ormcp_server.py

Using MCP Inspector dev mode (requires source distribution):

mcp dev src/ormcp_server.py

Using MCP Inspector without source code:

If you have the ormcp-server package installed, you can use MCP Inspector to explore the server's capabilities:

# Using the installed package
npx @modelcontextprotocol/inspector python -m ormcp_server

# Or if you have the command in PATH
npx @modelcontextprotocol/inspector ormcp-server

This allows you to interactively test and explore ORMCP Server tools without needing the source distribution.

HTTP or SSE Transport Support

Note: ORMCP defaults to stdio transport, which is what most desktop AI clients (e.g., Claude Desktop) use out of the box. HTTP mode (Streamable HTTP transport) is also fully supported for standalone/networked deployments — see the HTTP mode interaction guide for details. Some clients (e.g., Gemini CLI) currently require HTTP mode.

You can start the ORMCP server in HTTP mode from the command line:

# Basic HTTP mode
python src/ormcp_server.py --transport http

# Or using the CLI
ormcp-server --transport http

Customize host and port:

python src/ormcp_server.py --transport http --host 0.0.0.0 --port 9000

# Or using CLI
ormcp-server --transport http --host 0.0.0.0 --port 9000

Available command-line options:

• --transport: Choose between "stdio" (default) or "http"

• --host: Set the host address (default: 127.0.0.1, only used in HTTP mode)

• --port: Set the port number (default: 8080, only used in HTTP mode)

Quick HTTP setup:

python src/ormcp_server.py --transport http
# or
ormcp-server --transport http

Make sure you have uvicorn installed as a dependency since HTTP mode uses it to serve the application.

Usage in HTTP Mode

The MCP server running in HTTP mode isn't designed to be accessed directly through a web browser. It's an API server that expects specific MCP protocol messages, not HTTP GET requests to the root path.

Summary

• Use ormcp-server CLI for the cleanest, recommended experience.

• Use direct python src/ormcp_server.py for simple runs with source distribution.

• Use mcp dev or fastmcp run for advanced dev/testing scenarios with source distribution.

Expected Output

... - microservice_ensure - INFO - Checking the Gilhari microservice at http://localhost:80/gilhari/v1/health/check
... - microservice_ensure - INFO - Health endpoint check passed for my-gilhari-microservice
... - INFO - Gilhari microservice is available
... - INFO - ORMCP server name: ORMCPServerDemo
... - INFO - GILHARI BASE URL: http://localhost:80/gilhari/v1/
🟢 This ORMCP server is configured to expose just the READONLY MCP tools
... - INFO - Log file: <temp directory>/ormcp_server_debug.log
🟢 ORMCP server v0.7.x starting in stdio (or HTTP) mode ...

If no Gilhari microservice answers at GILHARI_BASE_URL, ORMCP stops with a message naming the address it checked, followed by a 💡 "What to do" hint.

Containerized Deployment (MCP Registries)

For deployment via MCP registries such as Glama, a start.sh script is provided in the root of this repository. It handles installing and launching ORMCP Server in a containerized environment. See the script for required environment variables and configuration details.

MCP Client Configuration

Claude Desktop

Platform-specific config file locations and path setup: macOS · Windows · Linux

Option 1: Using Command Name (Requires PATH Configured)

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Option 2: Using Full Path (Recommended for Windows)

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "C:\\Users\\<YourUsername>\\AppData\\Roaming\\Python\\Python313\\Scripts\\ormcp-server.exe",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

To find your exact installation path:

# Windows (PowerShell)
(Get-Command ormcp-server).Source

# Windows (Command Prompt)
where ormcp-server

# Linux/Mac
which ormcp-server

# Any platform
pip show -f ormcp-server | grep "ormcp-server.exe"  # Windows
pip show -f ormcp-server | grep "ormcp-server$"     # Linux/Mac

Option 3: Direct Python Execution

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "python", 
      "args": [
        "-m",
        "ormcp_server"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Option 4: Using FastMCP (For Developers with Source Distribution)

{
  "mcpServers": {
    "ORMCPServerDemo": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "<path_to_your_ormcp-server-project>/src/ormcp_server.py"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Option 5: HTTP Mode (Custom Connector)

claude_desktop_config.json starts local MCP servers over stdio only (Options 1–4); a server started from it with --transport http won't connect. Claude Desktop reaches an MCP server over HTTP only as a custom connector:

1. Start ORMCP in HTTP mode: ormcp-server --transport http --port 8080

2. Make it reachable at a public HTTPS URL, e.g. with cloudflared or ngrok as described for OpenAI GPTs. Custom connectors are connected from Anthropic's cloud, not from your computer, so localhost URLs don't work.

3. Allow the tunnel's host name, otherwise ORMCP's Host/Origin protection rejects the requests (HTTP 421): e.g. ALLOWED_HOSTS=<your-tunnel-host>.

4. In Claude Desktop: Settings → Connectors → Add custom connector, and enter the public URL followed by /mcp, e.g. https://<your-tunnel-host>/mcp.

Custom connectors are available on all Claude plans (the Free plan is limited to one); on Team and Enterprise plans an administrator may need to allow them.

Notes:

• ORMCPServerDemo is the default name of the ORMCP server.

• Replace <YourUsername> with your actual Windows username

• If you are providing a port number of the associated Gilhari microservice through the "GILHARI_BASE_URL" environment variable, make sure that is the port where that Gilhari microservice is listening.

• Claude Desktop connects to an HTTP-mode ORMCP server only as a custom connector at a public HTTPS URL (Option 5); for a local server, use stdio (Options 1–4).

Gemini CLI

Update the Gemini settings.json file:

{
  "mcpServers": {
    "my-ormcp-server-http": {
      "httpUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}

Note: Gemini CLI currently requires HTTP mode.

OpenAI GPTs (Developer Mode)

To connect the ORMCP server to a custom GPT in developer mode, the server must be running in HTTP mode and be accessible from a public URL.

1. Prepare the Backend:

   • First, ensure the Gilhari microservice is compiled and running in its Docker container as per the setup instructions.

   • Use curl to verify the Gilhari service is responsive:

     curl -i http://localhost:80/gilhari/v1/getObjectModelSummary/now

2. Configure and Run the ORMCP Server:

   • Set the required environment variables for the ORMCP server to connect to Gilhari.

     export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
     export MCP_SERVER_NAME="MyORMCPServer"
     export GILHARI_TIMEOUT="30"
     export LOG_LEVEL="INFO"

   • Start the ORMCP server in HTTP mode, as this is required for web-based clients.

     # Run from the project's root directory
     ormcp-server --transport http --port 8080

3. Expose the Server with a Public URL: OpenAI's servers need a public web address to reach your local ORMCP server. Use a tunneling service like cloudflared or ngrok to create a secure public URL that forwards to your local machine.

   • Option A: Using cloudflared (Recommended)

     • In a new terminal, start a Cloudflare tunnel pointing to your server's port.

       cloudflared tunnel --url http://localhost:8080

     • cloudflared will provide a persistent public URL (e.g., https://<your-tunnel-name>.trycloudflare.com).

   • Option B: Using ngrok

     • In a new terminal, start ngrok to forward traffic to port 8080.

       ngrok http 8080

     • ngrok will provide a temporary public HTTPS URL (e.g., https://random-string.ngrok-free.app). Note that this URL changes every time you restart ngrok on the free plan.

4. Connect to Your Custom GPT:

   • Take the public URL generated by cloudflared or ngrok.

   • Append /mcp to the end of this URL. The final result will be your MCP endpoint, for example: https://<your-public-url>/mcp.

   • In your GPT's configuration settings (Settings → Apps & Connectors → Create), paste this complete URL into the MCP Server URL field. GPT will then discover and connect to the tools provided by your ORMCP server.

Other MCP Clients

• Connect to ORMCP server and use the MCP compatible ORM tools provided by the ORMCP server.

• Configure according to your client's MCP server setup requirements using the appropriate transport mode (STDIO or HTTP).

• 📚 Integration Guides: See detailed documentation on connecting to ORMCP Server:

  • MCP Protocol Reference - Low-level JSON-RPC protocol details

  • Using the ORMCP Client Example - Python client usage guide

  • Interacting with ORMCP Server in STDIO Mode - STDIO transport guide

  • Interacting with ORMCP Server in HTTP Mode - HTTP transport guide

  • Additional guides available in the documentation repository (also included in the source distribution)

MCP Tools Reference

ORMCP Server provides the following MCP tools for interacting with your database.

📖 Detailed API Documentation: For complete parameter specifications and technical details, see the MCP Tools API Reference.

💡 Working Examples: See real-world usage examples in the examples directory.

Attribute names, not column names: filters, projections and aggregates use attribute names from the object model summary (getObjectModelSummary), not database column names.

Classes without a unique primary key: a class marked DB_PRIMARY_KEY_EXISTS FALSE in the object model summary may have several objects with the same key values. Use query, access, getAggregate, and update2/delete2 with a filter for it; getObjectById, update and delete are not supported.

Filters: the filter parameter of query, getAggregate, update2 and delete2 is a condition in SQL WHERE-clause syntax (without the word WHERE), evaluated in the database — e.g. isactive = true AND tier IN ('Gold', 'Platinum'). A query filter may end with ORDER BY and can test referenced objects with path expressions such as COUNT(thisObject.listCustomerorder.id) > 10. See Filter syntax for operators, literal formats and examples.

Core Operations

getObjectModelSummary

Retrieve information about the underlying object model.

Returns: Information about classes (types), attributes, primary keys, and relationships in your domain model.

query

Query objects with filtering and relationship traversal.

Parameters:

• className (string): Type of objects to query

• filter (string, optional): SQL-like WHERE clause for filtering

• maxObjects (integer, optional): Maximum number of objects to retrieve (-1 for all, default: -1)

• deep (boolean, optional): Include referenced objects in results (default: true)

• operationDetails (string, optional): JSON array of operational directives for fine-tuning queries. Supports GraphQL-like operations such as:

  • projections: Retrieve only specific attributes

  • ignore or follow: Control referenced object branches

  • filters: Apply filters to referenced objects

  Projections must include the class's primary-key attributes, except for classes marked DB_PRIMARY_KEY_EXISTS FALSE.

• allowDuplicates (boolean, optional): Return every qualifying row as its own object, even when rows have identical primary key values (default: false; requires Gilhari 0.8.7+)

Returns: A JSON array of the qualifying objects ([] if none qualify)

getObjectById

Retrieve a specific object by its primary key.

Parameters:

• className (string): Type of object to retrieve

• primaryKey (object): Primary key values (single value or composite key object)

• deep (boolean, optional): Include referenced objects (default: true)

• operationDetails (string, optional): Operational directives for fine-tuning queries

Returns: The object as a single JSON object, or null if no object has that id

access

Retrieve object(s) referenced by a specific attribute of a referencing object.

Parameters:

• className (string): Type of the referencing object

• jsonObject (object): The referencing object containing the reference

• attributeName (string): Name of the attribute whose referenced value(s) to retrieve

• deep (boolean, optional): Include referenced objects of retrieved objects as well (default: true)

• operationDetails (string, optional): Operational directives for fine-tuning queries

Returns: For a collection attribute, a JSON array of the referenced objects ([] if none); otherwise the referenced object

getAggregate

Calculate aggregate values across objects (COUNT, SUM, AVG, MIN, MAX).

Parameters:

• className (string): Type of objects to aggregate

• attributeName (string): Attribute to perform aggregation on

• aggregateType (string): Type of aggregation - COUNT, SUM, AVG, MIN, MAX

• filter (string, optional): SQL-like WHERE clause to filter objects before aggregation

Returns: A single JSON value (e.g. 1000 for COUNT), not a list of objects

get_server_version

Get the ORMCP Server version.

Returns: A JSON object with version, description, and gilhari_base_url (the Gilhari microservice this server uses; added in 0.7.1)

Data Modification Operations

Note: These tools are only exposed if READONLY_MODE=False is set — READONLY_MODE defaults to True, so insert, update, update2, delete, and delete2 are not available out of the box. See Configuration for ORMCP Server above.

insert

Save one or more JSON objects to the database.

Parameters:

• className (string): Type of objects to insert

• jsonObjects (array): List of JSON objects to save to the database

• deep (boolean, optional): Save referenced objects as well (default: true)

Returns: A short confirmation message (plain text, not JSON) when the operation succeeds; failures are reported as errors

update

Update one or more existing objects with new values. update replaces each stored object with the one given (matched by primary key), so include all of its attributes. To change only some attributes, use update2 with a filter on the primary key.

Parameters:

• className (string): Type of objects to update

• jsonObjects (array): List of complete objects with updated values (each with its primary key and all other attributes)

• deep (boolean, optional): Update referenced objects as well (default: true)

Returns: A short confirmation message (plain text, not JSON) when the operation succeeds; failures are reported as errors

update2

Bulk update objects matching filter criteria.

Parameters:

• className (string): Type of objects to update

• filter (string): SQL-like WHERE clause to identify objects to update

• newValues (array): Alternating list of attribute names and their new values, e.g. ["status", "active", "age", 40]

• deep (boolean, optional): Update referenced objects as well (default: true)

Returns: The number of top-level objects updated

delete

Delete specific objects from the database.

Parameters:

• className (string): Type of objects to delete

• jsonObjects (array): Objects to delete (primary keys required for identification)

• deep (boolean, optional): Delete referenced objects as well (default: true)

Returns: A short confirmation message (plain text, not JSON) when the operation succeeds; failures are reported as errors

delete2

Bulk delete objects matching filter criteria.

Parameters:

• className (string): Type of objects to delete

• filter (string, optional): SQL-like WHERE clause to identify objects to delete (empty string deletes all objects of the specified class)

• deep (boolean, optional): Delete referenced objects as well (default: true)

Returns: The number of top-level objects deleted

Note: READONLY_MODE defaults to True, so the MCP tools for data modification operations (insert, update, update2, delete, delete2) are not exposed to MCP clients unless you explicitly set READONLY_MODE=False.

Troubleshooting

For common issues and solutions, see the Complete Troubleshooting Guide.

Quick Troubleshooting

Installation Issues:

• Command not found → See your platform guide for PATH configuration: macOS · Windows · Linux

• Externally managed environment → Use virtual environment (see troubleshooting guide)

• Empty executable → Reinstall package

• Missing dependencies → pip install --force-reinstall ormcp-server

• Upgrading from v0.6.2 or earlier and getting a fastmcp ImportError → See fastmcp Import Error After Upgrade

Gilhari Example Issues:

• Shell script permission denied → chmod +x scripts/*.sh gilhari/*.sh or use sh gilhari/build.sh (Linux/Mac)

• Database connection errors → Verify JDBC driver in Gilhari

Runtime Issues:

• Server won't start → Check that Gilhari is running and that GILHARI_BASE_URL has its port (docker ps shows a container's host port, e.g. 0.0.0.0:8130->8081/tcp means 8130); the error message names the address ORMCP checked

• Details of a run → see the log file (ormcp_server_debug.log in the system's temp directory, or ORMCP_LOG_FILE)

• Database connection errors → Verify JDBC driver in Gilhari

• MCP client connection issues → Check config file syntax

Enable Debug Mode:

# Linux/Mac
export LOG_LEVEL=DEBUG
ormcp-server

# Windows (Command Prompt)
set LOG_LEVEL=DEBUG
ormcp-server

# Windows (PowerShell)
$env:LOG_LEVEL="DEBUG"
ormcp-server

Get Help:

• Documentation: github.com/softwaretree/ormcp-docs

• Issues: github.com/softwaretree/ormcp-docs/issues

• Email: ormcp_support@softwaretree.com

Development

Testing

For testing and development with the source distribution:

# Download source distribution
pip download --no-binary :all: ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

Gilhari Microservice Development

• ORMCP Server leverages Gilhari software, a RESTful microservice framework for JSON data integration with databases.

• You first create a custom Gilhari microservice based on the object relational data models of your application.

• An object relational mapping (ORM) specification defines and controls the scope and shape of your object model corresponding to your relational model.

• The ORM specification is defined declaratively in a text file (.jdx) based on a simple grammar.

• You may be able to reverse-engineer ORM specification from an existing database schema using tools/examples provided with Gilhari SDK. Check the examples\JDX_ReverseEngineeringJSONExample directory.

• The reverse-engineering example is also available online at github.com/SoftwareTree/JDX_ReverseEngineeringJSONExample

• For details on creating custom Gilhari microservices, refer to the Gilhari SDK documentation included in the source distribution package.

• Although an ORMCP server may start a Gilhari microservice if configured to do so (using GILHARI_IMAGE, GILHARI_NAME, and GILHARI_PORT environment variables), it is recommended that you start your custom Gilhari microservice before using the ORMCP server. Also, please make sure that the port number in the 'GILHARI_BASE_URL' environment variable for the ORMCP server matches the port number on which the custom Gilhari microservice is listening for incoming REST calls; ORMCP checks that address at start-up.

Contributing

Thank you for your interest in ORMCP Server!

🚫 No Code Contributions at This Time

ORMCP Server is proprietary software. We are not accepting code contributions, pull requests, or feature submissions.

🐞 Feedback and Bug Reports

We welcome feedback on the beta version! You can help us improve ORMCP Server by:

• Reporting bugs or issues

• Suggesting improvements

• Sharing your experience

How to Provide Feedback

• GitHub Issues: Report issues or suggestions

• Email: ormcp_support@softwaretree.com

Any feedback you provide may be used by Software Tree to improve the product, without any obligation to credit or compensate you.

Third-Party Software

Gilhari and JDX Dependency: ORMCP Server requires the Gilhari microservice to function, which in turn depends on JDX, the underlying ORM technology used by Gilhari. Both are proprietary Software Tree products. Gilhari and JDX incorporate various third-party software components. For complete details of these third-party components and their licenses, see the LICENSE file in the Gilhari SDK, or visit: https://www.softwaretree.com/v1/products/gilhari/ and https://www.softwaretree.com/v1/products/jdx/jdx.html

Python Dependencies: ORMCP Server uses the following open-source Python libraries, each governed by their respective licenses:

• mcp (Model Context Protocol SDK)

• fastmcp (FastMCP framework)

• httpx (HTTP client library)

• pydantic (Data validation library)

• uvicorn (ASGI server)

• requests (HTTP library)

License

ORMCP Server is proprietary software owned by Software Tree, LLC. See the LICENSE file for complete terms.

Beta Evaluation: ORMCP Server is currently available as a beta product under an evaluation license. This allows free use for testing and evaluation purposes for a limited evaluation period (30 days from the date of installation).

Gilhari and JDX Dependency: ORMCP Server requires the Gilhari microservice to function, which in turn depends on JDX, the underlying ORM technology used by Gilhari. Both are proprietary Software Tree products under their own license agreements. By using ORMCP Server, you agree to comply with the Gilhari License and the JDX License as well. Gilhari and JDX incorporate various third-party software components — for details, see the LICENSE file in the Gilhari SDK, or visit https://www.softwaretree.com/v1/products/gilhari/ and https://www.softwaretree.com/v1/products/jdx/jdx.html.

Commercial Licensing: Use of ORMCP Server beyond the evaluation period is subject to then-applicable Software Tree licensing terms. For information or to express interest, contact Software Tree at ormcp_support@softwaretree.com or visit https://www.softwaretree.com.

Support & Resources

• Documentation: Complete documentation and guides

• Platform Guides: macOS · Windows · Linux

• Working Examples: Browse Examples | Examples Guide - Real-world use cases and integrations

• Example Microservice: gilhari_example1 Repository

• Bug Reports: Report issues

• Email Support: ormcp_support@softwaretree.com

• Gilhari Support: Software Tree Gilhari Documentation

• MCP Protocol: Official MCP Site

• Install ORMCP Server: pip install ormcp-server — no beta token needed. See softwaretree.com/products/ormcp for full setup instructions.

Made with ❤️ for the AI and database community