Enables human-on-the-loop validation by sending notifications to Telegram, allowing users to approve or reject critical, destructive, or irreversible actions before an AI agent executes them.
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 proceedsWithout ORACLE-H: 4-step workflow succeeds ~81.5% of the time. With ORACLE-H: Same workflow succeeds ~99.6% of the time.
MCP Tools
Tool | Description |
| Submit a risky action for human approval. Returns a |
| Poll the decision until approved, rejected, or expired. |
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.onlineInstallation
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)
Add to cline_mcp_settings.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"
}
}
}
}Roo Code (VS Code)
Add to .roo/mcp.json (project-level) or global MCP settings:
{
"mcpServers": {
"oracle-h": {
"command": "npx",
"args": ["-y", "oracle-h-mcp"],
"env": {
"ORACLE_SIGNATURE_KEY": "<your-signature-key>",
"ORACLE_BASE_URL": "https://oracle-h.online"
}
}
}
}GitHub Copilot (VS Code)
Add to VS Code MCP settings (settings.json):
{
"github.copilot.mcp": {
"oracle-h": {
"command": "npx",
"args": ["-y", "oracle-h-mcp"],
"env": {
"ORACLE_SIGNATURE_KEY": "<your-signature-key>",
"ORACLE_BASE_URL": "https://oracle-h.online"
}
}
}
}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.onlineLangGraph (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
Agent calls with action, rationale, projected impact, and TTL
Human receives a Telegram notification with full context and risk analysis
Human taps Approve or Reject directly in Telegram
Agent polls until decision arrives
Agent proceeds or aborts based on the human decision
The system includes:
🛡️ Anti-hallucination Watchdog — detects context truncation before submitting
📊 Reliability Calculator — shows the statistical improvement (81.5% → 99.6%)
⏳ TTL / Expiry — requests auto-expire if no human response within the configured timeout
🔐 Bearer Token Auth — each agent has a unique signature key
🔒 HMAC-SHA256 signed webhooks — tamper-proof decisions
System Prompt Snippet
Add this to your agent's system prompt to ensure ORACLE-H is always used correctly:
## Human Approval Gate — ORACLE-H (MANDATORY)
Call oracle_validate BEFORE executing any action in these categories:
DESTRUCTIVE: Deleting files, dropping databases, removing users, git force-push
EXTERNAL WRITES: Sending emails, posting to APIs, submitting forms
FINANCIAL: Payments, billing changes, subscription modifications
INFRASTRUCTURE: Deployments, server config, DNS, environment variables
POLLING PROTOCOL:
After oracle_validate, poll oracle_poll_status every 10-15 seconds until:
- "approved" → proceed
- "rejected" → STOP, inform user, propose alternatives
- "expired" → STOP, ask user if they want to retry
HARD RULES:
- NEVER execute before "approved"
- If oracle_validate is unreachable: BLOCK the action, inform user
- Read-only operations do NOT require oracle_validateAPI
Full API documentation: oracle-h.online/llms.txt OpenAPI spec: oracle-h.online/openapi.json
License
MIT