ORACLE-H MCP Server

ORACLE-H MCP Server

Human-on-the-Loop validation for autonomous AI agents — via Model Context Protocol

What is ORACLE-H?

ORACLE-H is a safety infrastructure that acts as a mandatory checkpoint for autonomous AI agents. Before executing any critical, destructive, or irreversible action, the agent submits it for human approval via Telegram. The human decides with a single tap.

Agent → oracle_validate → Human gets Telegram alert → Approve/Reject → Agent proceeds

Without ORACLE-H: 4-step workflow succeeds ~81.5% of the time. With ORACLE-H: Same workflow succeeds ~99.6% of the time.

MCP Tools

Quick Start (Demo — no signup required)

# Test immediately with the public demo key
ORACLE_SIGNATURE_KEY=demo-signature-key-change-in-production
ORACLE_BASE_URL=https://oracle-h.online

Installation

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "oracle-h": {
      "command": "npx",
      "args": ["-y", "oracle-h-mcp"],
      "env": {
        "ORACLE_SIGNATURE_KEY": "<your-signature-key>",
        "ORACLE_BASE_URL": "https://oracle-h.online"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP settings:

{
  "oracle-h": {
    "command": "npx",
    "args": ["-y", "oracle-h-mcp"],
    "env": {
      "ORACLE_SIGNATURE_KEY": "<your-signature-key>",
      "ORACLE_BASE_URL": "https://oracle-h.online"
    }
  }
}

Cline (VS Code)

// File: cline_mcp_settings.json
{
  "mcpServers": {
    "oracle-h": {
      "command": "npx",
      "args": ["-y", "oracle-h-mcp"],
      "env": {
        "ORACLE_SIGNATURE_KEY": "demo-signature-key-change-in-production",
        "ORACLE_BASE_URL": "https://oracle-h.online"
      }
    }
  }
}

Roo Code (VS Code)

// File: .roo/mcp.json (project-level)
{
  "mcpServers": {
    "oracle-h": {
      "command": "npx",
      "args": ["-y", "oracle-h-mcp"],
      "env": {
        "ORACLE_SIGNATURE_KEY": "demo-signature-key-change-in-production",
        "ORACLE_BASE_URL": "https://oracle-h.online"
      }
    }
  }
}

GitHub Copilot (VS Code)

Add to VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "oracle-h": {
      "command": "npx",
      "args": ["-y", "oracle-h-mcp"],
      "env": {
        "ORACLE_SIGNATURE_KEY": "demo-signature-key-change-in-production",
        "ORACLE_BASE_URL": "https://oracle-h.online"
      }
    }
  }
}

n8n

Use the MCP Client Tool node in n8n, running via supergateway:

npx -y supergateway --stdio "npx -y oracle-h-mcp" --port 8811

Then connect n8n's MCP Client Tool to http://localhost:8811/sse

Zed Editor

Add to settings.json:

{
  "context_servers": {
    "oracle-h": {
      "command": {
        "path": "npx",
        "args": ["-y", "oracle-h-mcp"]
      },
      "env": {
        "ORACLE_SIGNATURE_KEY": "<your-signature-key>",
        "ORACLE_BASE_URL": "https://oracle-h.online"
      }
    }
  }
}

Continue.dev

Create .continue/mcpServers/oracle-h.yaml:

name: oracle-h
version: 1.0.0
schema: v1
mcpServers:
  - name: oracle-h
    command: npx
    args:
      - -y
      - oracle-h-mcp
    env:
      ORACLE_SIGNATURE_KEY: <your-signature-key>
      ORACLE_BASE_URL: https://oracle-h.online

LangGraph (Python)

from langchain_mcp_adapters.client import MultiServerMCPClient

async with MultiServerMCPClient({
    "oracle-h": {
        "command": "npx",
        "args": ["-y", "oracle-h-mcp"],
        "env": {
            "ORACLE_SIGNATURE_KEY": "your-key",
            "ORACLE_BASE_URL": "https://oracle-h.online"
        },
        "transport": "stdio"
    }
}) as client:
    tools = client.get_tools()

How it works

1. Agent calls oracle_validate with action, rationale, projected impact, and TTL
2. Human receives a Telegram notification with full context and risk analysis
3. Human taps Approve or Reject directly in Telegram
4. Agent polls oracle_poll_status until decision arrives
5. Agent proceeds or aborts based on the human decision

The system includes:

• 🛡️ Anti-hallucination Watchdog — detects context truncation before submitting
• 📊 Reliability Calculator — shows the statistica