home / mcp / ordinal-mcp mcp server

Ordinal-MCP MCP Server

Provides an ordinal, multi-level message bus for structured AI-human coordination and decision making.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "bobbyhiddn-ordinal-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/Ordinal-MCP",
        "ordinal-mcp"
      ]
    }
  }
}

Ordinal-MCP provides a structured ordinal bus that coordinates communication between AI agents and human operators. It enables upward oracle calls and downward task delegation with typed, archived messages to keep interactions clear and auditable. This server is built to support controlled human-in-the-loop decisions within agent systems.

How to use

You will run the MCP server locally or in your infrastructure and connect it to an MCP client. Use the provided command-line tools to send oracle questions, monitor pending calls, and review completed exchanges. When a subagent needs guidance, Rhode answers via its own LLM. When Rhode needs human input, the system escalates to the human oracle through Telegram, and the answer flows back to the requester.

Key usage patterns include: initiating oracle calls from different ordinal levels, checking bus status to see pending and completed exchanges, and inspecting history to audit past decisions. Use the standard JSON-based bus directory to inspect requests, responses, and archived conversations. If a subagent’s query requires human judgment, Rhode will indicate that in its answer and the subagent can re-ask with a higher from_level to escalate.

How to install

Prerequisites: Python 3.13 or newer and the uv runtime for the command-line interface.

1) Clone the project repository.

2) Change into the repository directory.

3) Install and start the MCP runtime. You can synchronize dependencies with uv and prepare the environment as shown.

4) Start the standalone server for testing.

Configuration and operation

The server runs as an MCP server configured to be started via a standard stdio command. Use the following approach to connect to an MCP client in your project and define the ordinal bus interaction: add a stdio MCP server entry pointing to the runtime and the ordinal-mcp module, then start the orchestration.

Tools and endpoints

The Ordinal-MCP provides a set of tools to interact with the bus and manage oracle calls. You can send questions, check current pending calls, respond to oracle calls, and view exchange histories. The available tools are listed below with their purposes and usage notes.

Notes and troubleshooting

- Ensure the bus directory is writable by the running process so requests, responses, and history can be written and archived correctly.

- When escalating to the human oracle, make sure the Telegram integration is configured and the human responder is ready to reply with the required format.

Available tools

oracle_call

Send a question to the appropriate oracle and wait for a response, handling from_level, to_level, and context parameters.

bus_status

Check the current state of the bus, including pending requests, responses, and history counts.

list_pending_calls

List all oracle calls that are currently waiting for a response.

respond_to_oracle_call

Provide an answer to a pending oracle call, updating the bus with the responder and timestamp.

bus_history

View recent completed exchanges with optional limits to control how many records are shown.