Skip to content
AgentCTX

Secure MCP Hooks

Secure MCP Hooks

Section titled “Secure MCP Hooks”

AgentCTX wraps every MCP tool call with security hooks — scope enforcement, budget checks, and audit logging. This guide covers how to configure and extend these protections.

The Security Pipeline

Section titled “The Security Pipeline”

Every tool call passes through 5 security checks before reaching the MCP backend:

>t github.issues.create title="Fix bug"
   ↓
1. RBAC Check        → Does this agent have the "issues" role?
2. Scope Enforcement  → Is this tool within the agent's allowed scope?
3. Budget Check       → Does the agent have enough token budget?
4. Alignment Check    → Does this action match the agent's stated goal?
5. Audit Log          → Record the operation (signed by sidecar)
   ↓
MCP Backend (github)

RBAC Configuration

Section titled “RBAC Configuration”

Control which agents can access which tools via role-based access control:

backends:
  - id: github
    roles: [code, issues]     # Only agents with these roles
  - id: admin-panel
    roles: [admin]            # Restricted to admin agents
  - id: filesystem
    roles: [default]          # Available to all agents

Ring-Based Access

Section titled “Ring-Based Access”

Roles are organized in concentric rings (inner = more privileged):

Ring 0: admin        ← Full access
Ring 1: code, issues ← Development tools
Ring 2: read         ← Read-only tools
Ring 3: default      ← Basic tools only

Scope Enforcement

Section titled “Scope Enforcement”

Plugins declare their required scopes in actx-plugin.yaml:

scopes:
  backends: [github]           # Can only access GitHub backend
  planes: [tools, knowledge]   # Can only use t and k planes
  operations: [search, call]   # Can only search and call (no delete)

The scope enforcement middleware (pipeline position 8) rejects any operation outside declared scopes.

Budget Controls

Section titled “Budget Controls”

Set per-agent or per-session token budgets:

economy:
  budget:
    perSession: 100000    # Max tokens per session
    perDay: 500000        # Max tokens per day
    perCall: 10000        # Max tokens per individual tool call

When a budget is exceeded, the budget middleware (pipeline position 3) rejects the request with a BUDGET_EXCEEDED error code.

Plugin Auditing

Section titled “Plugin Auditing”

Before activating any plugin, run the static analyzer:

Terminal window
actx audit ./my-plugin/

This checks:

  • Declared permissions match actual code behavior
  • No eval(), dynamic require(), or unsafe patterns
  • Dependencies don’t have known vulnerabilities
  • Scope boundaries are respected

Audit Logging

Section titled “Audit Logging”

Every tool call is logged by the audit middleware (pipeline position 13):

{
  "timestamp": "2026-03-20T21:00:00Z",
  "agent": "agent-abc123",
  "operation": ">t github.issues.create",
  "args": { "title": "Fix bug" },
  "result": { "ok": true, "ms": 42 },
  "signed": true,
  "digest": "a1b2c3d4..."
}

All audit entries are signed by the sidecar for tamper evidence.

See Also

Section titled “See Also”