io.github.tponscr-debug/oracle-h
Human approval gate for AI agents. Critical actions approved or rejected by a human via Telegram.
Ask AI about io.github.tponscr-debug/oracle-h
Powered by Claude Β· Grounded in docs
I know everything about io.github.tponscr-debug/oracle-h. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
| Tool | Description |
|---|---|
oracle_validate | Submit a risky action for human approval. Returns a request_id. |
oracle_poll_status | 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.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
- Agent calls
oracle_validatewith 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
oracle_poll_statusuntil 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_validate
API
Full API documentation: oracle-h.online/llms.txt OpenAPI spec: oracle-h.online/openapi.json
License
MIT
