MachineElf M2M Gateway

MachineElf is a strict JSON machine-to-machine gateway for autonomous AI agents that need loop-safe human-operator alert routing. It is designed for LangChain, CrewAI, AutoGPT-style planners, crawlers, and LLM orchestration frameworks that hit critical sandbox exceptions, blocked workflows, unsafe retry loops, or operator escalation points.

Public API base:

https://machineelf.onrender.com

Marketplace:

https://rapidapi.com/Atmic/api/machineelf-notification-bridge

Agent Discovery

• OpenAPI: https://machineelf.onrender.com/openapi.json
• Agent manifest: https://machineelf.onrender.com/.well-known/ai-plugin.json
• LLM context: https://machineelf.onrender.com/llms.txt
• Full LLM context: https://machineelf.onrender.com/llms-full.txt
• Swagger docs: https://machineelf.onrender.com/docs
• Sitemap: https://machineelf.onrender.com/sitemap.xml

What Agents Use It For

• Route urgent failures from cloud sandboxes to a human operator.
• Escalate blocked autonomous workflows instead of silently failing.
• Avoid duplicate notification charges during retry loops with X-Idempotency-Key.
• Use strict Pydantic v2 JSON schemas instead of loose tool strings.
• Register future permitted HTML cleanup plans through a strict scrape-template contract.

Primary Tool

POST /api/v1/execute

Routes one validated alert to a human operator through ntfy.sh.

Consumer-visible headers through RapidAPI:

X-Idempotency-Key: <unique caller-generated key>
Content-Type: application/json

RapidAPI injects the backend X-API-Key as a hidden Gateway secret header. Direct non-RapidAPI deployments still require a valid X-API-Key.

Example request body:

{
  "topic_key": "/machineelf-hidden-ops-channel",
  "title": "Agent Alert: Sandbox Failure",
  "message": "The autonomous run hit a critical cloud sandbox exception and paused for operator review.",
  "priority": 5,
  "max_steps": 1,
  "timeout_seconds": 30,
  "rationale": "Immediate human notification is required because the workflow cannot safely continue."
}

Pricing Metadata

• Priority 1-2 alert routing: $0.01
• Priority 3 alert routing: $0.03
• Priority 4-5 urgent alert routing: $0.07
• Fixed operational cost per successful alert: $0.001
• Net profit formula: markup_fee - cost

Successful notification transactions are written to profit_ledger.json through thread/process locked atomic ledger logic.

Other Tools

POST /api/v1/scrape

Authenticated strict-schema scrape-template registration endpoint. It validates permitted HTML cleanup planning requests and idempotency behavior but does not perform live scraping yet.

GET /api/v1/telemetry

Authenticated daily ledger summary for operators.

MCP Wrapper

The repository includes a no-dependency stdio MCP wrapper:

python mcp_server.py

MCP tools:

• machineelf_route_operator_alert
• machineelf_register_scrape_template

Configure:

MACHINEELF_BASE_URL=https://machineelf.onrender.com
MACHINEELF_API_KEY=<paid-or-configured-backend-key>

Local Development

python -m uvicorn main:app --host 127.0.0.1 --port 8000

Verify deployed discovery:

python verify_public_discovery.py https://machineelf.onrender.com

Client Examples

• Python RapidAPI call: examples/python_rapidapi_execute.py
• JavaScript RapidAPI call: examples/javascript_rapidapi_execute.mjs

Safety Model

MachineElf rejects unknown fields, loose strings, markdown code fences, escaped control blocks, hidden control characters, excessive step counts, excessive timeouts, non-JSON state-changing transport, missing idempotency keys, and invalid API keys.

Protected routes remain fail-closed even when public OpenAPI hides the backend X-API-Key for RapidAPI marketplace usability.