ORMCP Server

You can connect AI applications to relational databases using the ORMCP Server. It exposes a Model Context Protocol (MCP) interface that lets you query, insert, update, and manage data in a relational database through JSON-based objects, with optional real-time, bidirectional data flow and smooth integration with Gilhari microservices.

How to use

Set up ORMCP Server in stdio mode to run locally and connect to a Gilhari microservice. You will configure environment variables, start the server, and point your MCP client to the local server. You can also run the server in HTTP mode, but ensure you have a public URL if you plan to connect from remote clients.

Start with the standard, recommended path: run the ORMCP Server in stdio mode, which keeps the server on your machine and uses the built-in CLI entry point. Then configure your MCP client to talk to the server via the standard input/output transport.

To connect your AI client, provide a configuration entry that specifies the ormcp-server executable, the environment variables, and the server name. Here is a representative stdio configuration you can use as a starting point. It uses the ormcp-server command and passes the required environment variables.

{
  "mcpServers": {
    "my_ormcp_server": {
      "command": "ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer",
        "GILHARI_TIMEOUT": "30",
        "LOG_LEVEL": "INFO",
        "READONLY_MODE": "False",
        "GILHARI_NAME": "",
        "GILHARI_IMAGE": "",
        "GILHARI_HOST": "localhost",
        "GILHARI_PORT": "80"
      }
    }
  }
}

How to install

Prerequisites: Python 3.12+, Docker for Gilhari, and a JDBC driver for your target database.

1. Install ORMCP Server in your Python environment. Use the token-based private PyPI index for beta access if you have one, or install from PyPI when available.

2. Verify the installation and ensure the ormcp-server executable is available in your PATH.

3. Set up Gilhari and the Gilhari microservice image as described in the Gilhari setup steps, including pulling the Docker image and building your microservice container.

4. Prepare your environment and configuration values, such as the Gilhari base URL and server name.

5. Start the ORMCP Server in stdio mode.

# Linux/Mac
python -m venv .venv
source .venv/bin/activate

pip install ormcp-server

# Windows
python -m venv .venv
.\.venv\Scripts\activate
pip install ormcp-server

# Start in stdio mode
ormcp-server

Configuration and usage notes

Configure via environment variables to connect to Gilhari and identify your ORMCP server. The key variables are GILHARI_BASE_URL and MCP_SERVER_NAME, with optional timing and log level controls.

If you want to run the HTTP mode later, you can start the server in HTTP mode with a specific port, but you must provide a public URL if you intend to connect from remote clients.

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

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

Examples of common operations

You can perform standard data operations through MCP tools exposed by the server. These include querying, inserting, updating, and deleting objects, as well as retrieving object models and aggregates.

Tools and endpoints

The server provides a set of MCP tools for interacting with your database, including: getObjectModelSummary, query, getObjectById, access, getAggregate, insert, update, update2, delete, and delete2. Each tool accepts parameters described in the tool reference and works with JSON objects to map to relational data.

Troubleshooting

If you encounter issues starting the server, verify that Gilhari is running and that the base URL is reachable. Enable debug logging by setting LOG_LEVEL=DEBUG and retry. Check that the ORMCP Server executable is in your PATH and that Python dependencies are installed.

Development and support

For beta feedback, report issues or suggestions via the designated support channels. Contact details are provided in the support section.

Notes on integration with clients

Your MCP client should be configured to talk to the ORMCP Server via the stdio transport for local development. If you switch to HTTP mode, ensure the client supports HTTP transport and that the public URL is accessible from the client environment.

Appendix: Environment variables at a glance

GILHARI_BASE_URL: URL of the Gilhari microservice. MCP_SERVER_NAME: Identifier for your server. GILHARI_TIMEOUT: API timeout in seconds. LOG_LEVEL: Logging verbosity. READONLY_MODE: Expose only read operations. GILHARI_NAME: Name of the Gilhari microservice. GILHARI_IMAGE: Docker image name of the Gilhari microservice. GILHARI_HOST: Host for the Gilhari service. GILHARI_PORT: Port for the Gilhari service.

Security and access control

Enable READONLY_MODE if you want to expose only read operations. In that mode, modification tools are not exposed to MCP clients.

What you get with ORMCP Server

A lightweight, high-performance layer that translates MCP calls into relational data operations via Gilhari, with a declarative ORM specification and flexible query shapes.

Available tools

getObjectModelSummary

Retrieve information about the underlying object model, including classes, attributes, primary keys, and relationships.

query

Query objects with filtering and relationship traversal, returning matching objects.

getObjectById

Retrieve a specific object by its primary key.

access

Retrieve objects referenced by a specific attribute of a referencing object.

getAggregate

Compute aggregate values like COUNT, SUM, AVG, MIN, or MAX across objects.

insert

Save one or more JSON objects to the database.

update

Update existing objects with new values.

update2

Bulk update objects matching a filter criteria.

delete

Delete specific objects from the database.

delete2

Bulk delete objects matching a filter criteria.