🛡️ abhed-mcp

Universal Action Gate & Audit Ledger for AI Agent Tool Calls (Model Context Protocol)

Put any MCP agent's tool executions behind a deterministic policy gate: Allowed, Held for Human Approval, or Blocked — with every decision cryptographically sealed into a hash-chained audit ledger.

Live Demo Console · Abhed Engine Core (hackarena) · Report Bug

📌 Why Abhed MCP?

Autonomous AI agents in tools like Cursor, Claude Desktop, and VS Code have raw access to execute bash scripts, access databases, and trigger financial transactions. A single prompt injection can trigger unauthorized or destructive tool invocations.

abhed-mcp acts as a zero-trust firewall proxy between your AI agent and real-world tools:

  ┌─────────────────────────────────┐
  │  AI Agent (Claude / Cursor)     │
  └───────────────┬─────────────────┘
                  │ calls tool (e.g. `issue_refund(₹4500)`)
                  ▼
  ┌─────────────────────────────────┐
  │  🛡️ abhed-mcp Gateway           │
  └───────────────┬─────────────────┘
                  │ forwards to policy evaluator
                  ▼
  ┌─────────────────────────────────┐
  │  ⚙️ Abhed Decision Engine       │
  └───────────────┬─────────────────┘
                  │
        ┌─────────┴───────────────────────┐
        ▼                                 ▼
   [ Safe Action ]               [ High-Risk / Ambiguous ]
        │                                 │
     ALLOWED                       NEEDS_APPROVAL
        │                                 │
   Executes Tool                  Pushes to Mobile/Web Console
        │                         Human Approver confirms
        │                                 │
        └────────────────┬────────────────┘
                         ▼
  ┌──────────────────────────────────────────────┐
  │  📜 Hash-Chained, Ed25519 Sealed Ledger      │
  └──────────────────────────────────────────────┘

Related MCP server: actionproxy

⚡ Quick Start: Add to Your Favorite MCP Client

Add abhed to your client configuration with a single block:

1. Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "abhed": {
      "command": "npx",
      "args": ["-y", "github:HarshDubey23/abhed-mcp"],
      "env": {
        "ABHED_AGENT_KEY": "<your-agent-key>",
        "ABHED_URL": "https://kavach-os.vercel.app"
      }
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "abhed-guard": {
      "command": "npx",
      "args": ["-y", "github:HarshDubey23/abhed-mcp"],
      "env": {
        "ABHED_AGENT_KEY": "<your-agent-key>",
        "ABHED_APPROVAL_WAIT_SECONDS": "90"
      }
    }
  }
}

3. VS Code (Continue / Cline / Roo Code)

Add to your extension's MCP server settings under the mcpServers object.

⚙️ Configuration Variables

🧰 Native Built-in Tools

Four governance tools are provided out of the box to all connected agents:

1. abhed_start_task: Declares task intent and customer context. Abhed inspects this initial payload for prompt injection vectors.

2. abhed_check_approval: Asynchronously checks if a previously held action has received human approval and retrieves its execution payload.

3. abhed_finish_task: Closes the operational session and outputs an auditable summary into the permanent ledger.

4. abhed_whoami: Returns the active agent's role, associated organization, and granted resource limits.

🧪 Testing

The repository features comprehensive zero-dependency unit and integration tests:

git clone https://github.com/HarshDubey23/abhed-mcp.git
cd abhed-mcp
npm test

The test suite runs a live mock Abhed server over stdio verifying:

• ✅ Fast-path ALLOWED execution

• ⏳ Stateful NEEDS_APPROVAL polling and escalation

• ❌ Immediate BLOCKED policy enforcement

• 🔒 Rejection of undelegated tools before they leave the client environment

📄 License

Distributed under the MIT License. See LICENSE for details.