Tegata

Tegata

Enforceable authorization for MCP tool calls.

> Status: GA (v0.1.0). Core runtime, policy engine, and MCP tool call intercept are stable and tested. The API is frozen — no breaking changes until a semver-major bump. Trust Score and multi-reviewer consensus (everything beyond single-reviewer approval) are specified but not yet enforced (planned for v0.2 — see the feature matrix below). Install with npm install tegata.

MCP tool annotations like readOnlyHint are just hints — the spec itself says clients MUST treat them as untrusted, so nothing stops a malicious server from declaring readOnlyHint: true and deleting your database. MCP and A2A both define transport-layer authentication (OAuth 2.1, securitySchemes) — what neither defines is a workflow-level approval primitive: who approves a high-risk action, under what consensus, with what audit record. OWASP, NIST, and CSA all flag this gap but define no solution. Tegata fills it. (See [ADR-007](docs/adr/007-workflow-approval-vs-transport-authn.md) for the scope boundary.)

> Name origin: Tegata (手形) — Edo-period travel permits that certified a traveler's identity and authorized passage through checkpoints. Tegata does the same for AI agents.

Before / After

// ❌ Before: No governance — any agent can call any tool
await mcpClient.callTool("db:users:delete", { userId: "all" });
// Hope nothing goes wrong...

// ✅ After: Tegata intercepts and enforces approval
import { Tegata } from "tegata";

const created = Tegata.create();
if (!created.ok) throw new Error(created.error);
const tegata = created.value;

const result = await tegata.propose({
  proposer: "cleanup-bot",
  action: { type: "db:users:delete", riskScore: 90, reversible: false },
  params: { userId: "all" },
});
// → riskScore 90 exceeds threshold → auto-escalated to human reviewer
// → Decision logged to immutable audit trail

Where Tegata Fits

MCP    = Agent ↔ Tool    (Connection)
A2A    = Agent ↔ Agent   (Communication)
Tegata = Approval & Auth  (Governance) ← NEW

Tegata sits on top of MCP and A2A. It doesn't replace them — it adds the missing approval workflow layer (transport authn/authz stays with the protocols themselves; see [ADR-007](docs/adr/007-workflow-approval-vs-transport-authn.md)).

What Tegata is NOT

• Not a gateway — Solo.io agentgateway, MintMCP are infrastructure. Tegata defines the approval rules that gateways enforce.
• Not a policy engine — Cedar, OPA evaluate policies. Tegata orchestrates the approval workflow around them (Cedar plugin planned for v0.2).
• Not a communication protocol — A2A delivers messages. Tegata defines the semantics of approval on top of those messages.

Feature Status

What ships and works today in v0.1.0, and what is specified but deferred. Only single-reviewer approval (single) is enforced today; every multi-reviewer policy in the [Consensus Policies](#consensus-policies-should) table (majority, unanimous, quorum, weighted) is accepted by the config but not yet enforced by the runtime — those land in v0.2.

| Capability | Status | | -------------------------------------------------------- | --------- | | Tiered Approval (5 tiers) | ✅ v0.1.0 | | Capability-based authorization | ✅ v0.1.0 | | Policy-as-code (glob matching) | ✅ v0.1.0 | | Audit trail (append-only, event-sourced) | ✅ v0.1.0 | | MCP tool call intercept binding | ✅ v0.1.0 | | Consensus: single (single-reviewer) | ✅ v0.1.0 | | Execution modes: shadow / enforce | ✅ v0.1.0 | | Consensus: majority, unanimous, quorum, weighted | 🚧 v0.2 | | Dynamic Trust Score (EMA) | 🚧 v0.2 | | Cedar / OPA policy engine plugin | 🚧 v0.2 | | TegataReporter (opt-in telemetry) | 🚧 v0.2 | | Agent ↔ Agent approval (A2A binding) | 🚧 v0.3 |

Quick Start

import { Tegata } from "tegata";

// Tegata is constructed through a validating static factory
// (see ADR-009). Out-of-range config returns Err instead of
// silently corrupting runtime state.
const created = Tegata.create({
  defaultTier: "review", // Default approval level
  escalateAbove: 70, // Auto-escalate when riskScore > 70 (must be in [0, 100])
  timeoutMs: 30_000, // 30s timeout for reviewer response (must be > 0)
  defaultOnTimeout: "deny", // Deny if no response
  mode: "enforce", // "enforce" blocks denied/escalated actions; "shadow" logs only (ADR-006)
});
if (!created.ok) throw new Error(created.error);
const tegata = created.value;

// Register an agent
tegata.registerAgent({
  id: "deploy-bot",
  name: "Deploy Bot",
  role: "proposer",
  capabilities: ["ci:*:read", "ci:staging:deploy"],
  maxApprovableRisk: 40,
});

// Propose an action
const decision = await tegata.propose({
  proposer: "deploy-bot",
  action: {
    type: "ci:production:deploy",
    description: "Deploy v2.3.1 to production",
    riskScore: 85,
    reversible: true,
    rollbackPlan: "Revert to v2.3.0 via CI rollback pipeline",
  },
});

// decision.status: "escalated"
// → deploy-bot lacks capability for ci:production:*
// → riskScore 85 > maxApprovableRisk 40
// → Escalated to supervisor agent or human reviewer

proposer is a required string identifying who is requesting the action — typically an agent id ("deploy-bot"), but any identifier works ("human", "ci-runner"). Tegata rejects anonymous proposals because every audit-trail entry must carry attribution; unattributed actions defeat the point of a governance SDK. See [ADR-002](docs/adr/002-require-proposer-in-proposal.md) for the rationale.

Core Features

Tiered Approval (MUST)

5-level approval that adapts to risk and capability:

| Tier | Who Decides | When to Use | | ---------- | ---------------------------- | -------------------------------------------------------------- | | auto | No one (pass-through) | Read operations, cached queries | | notify | No one (log after execution) | Non-destructive writes (creating a draft, adding a comment) | | review | Another agent | Agent-to-agent approval (senior agent reviews junior's action) | | approve | Human | Human-in-the-loop (financial transaction > $10K, PII access) | | escalate | Higher authority | Risk threshold exceeded or reviewer lacks capability |

Tier selection is automatic based on riskScore, agent capabilities, and policy rules. Override per-action or globally via TegataConfig.

Capability-based Authorization (MUST)

Agents declare what they can do and what they can approve. If an agent proposes an action outside its capability scope, Tegata auto-escalates. No agent can approve its own proposals.

// Agent can read all CI data but only deploy to staging
capabilities: ["ci:*:read", "ci:staging:deploy"];
// Agent can approve deployments up to riskScore 40
maxApprovableRisk: 40;

ActionType follows domain:resource:operation convention with glob matching (ci:*:deploy matches ci:staging:deploy).

Policy-as-Code (MUST)

Define approval rules programmatically. No custom DSL — just TypeScript/JSON.

tegata.addPolicy({
  match: "db:*:write",
  tier: "approve", // All DB writes require human approval
  consensus: "single",
  reviewers: ["db-admin"],
});

tegata.addPolicy({
  match: "ci:production:*",
  tier: "review",
  consensus: "majority", // Specified now; multi-reviewer voting enforced in v0.2 (today: single-reviewer approval)
  reviewers: ["senior-dev", "sre-lead", "security-bot"],
  escalateAbove: 80,
});

Audit Trail (MUST)

Every proposal, decision, escalation, and timeout is logged immutably. Each entry includes who proposed, who reviewed, what was decided, and why.

const logs = tegata.getAuditLog({ since: "2026-04-01" });
// [{ proposalId, proposer, action, decisions[], finalStatus, timestamp }]

Dynamic Trust Score (SHOULD)

EMA-based inter-agent trust scoring. Agents that make good decisions see their trust rise; agents that cause incidents see it fall. Higher trust → more actions auto-approved.

TrustScore(t) = α × Performance(t) + (1 - α) × TrustScore(t-1)
// α = 0.3 default (configurable per domain)

Trust Score is optional — Tiered Approval works without it.

Consensus Policies (SHOULD)

When multiple reviewers are involved:

| Policy | Rule | | ----------- | --------------------------- | | single | Any one reviewer approves | | unanimous | All reviewers must approve | | majority | >50% of reviewers approve | | quorum | N of M reviewers approve | | weighted | Trust-score-weighted voting |

> v0.1.0 enforcement: only single is enforced by the runtime today. The > other four are accepted by addPolicy() config but not yet tallied — the > vote-counting engine lands in v0.2. See [Feature Status](#feature-status).

Regulatory Alignment

Tegata's design maps directly to emerging AI governance requirements:

• EU AI Act Article 14 (Aug 2026): Requires "effective human oversight" for high-risk AI. Tegata's approve and escalate tiers provide structured human intervention points.
• California SB-833 (Jul 2026): Mandates pre-execution review of AI-proposed actions in critical infrastructure. Tegata's tiered approval fulfills this with review/approve tiers.
• NIST NCCoE: Asks "how does an agent prove it is authorized to perform a specific action?" — this is exactly what Tegata defines.

Dogfooding

The author runs Tegata against his own Claude Code tool calls via a PreToolUse hook — every Bash, Edit, Write, MCP call, or subagent spawn is classified into an Action and passed through tegata.propose(). See [docs/dogfooding.md](docs/dogfooding.md) for the setup; replicable on any machine running Claude Code in a few minutes.

Roadmap

• v0.1 (Current): Agent → Tool approval workflow (MCP tool call intercept)
• v0.2: Cedar policy engine plugin + MCP Extension (SEP proposal)
• v0.3: Agent ↔ Agent approval workflow (A2A binding, after A2A spec stabilizes)

Tech Stack

• Language: TypeScript (source of truth) → JSON Schema auto-generation
• Wire Format: JSON-RPC 2.0 (same as MCP/A2A)
• Spec Style: RFC (MUST/SHOULD/MAY)
• License: Apache 2.0

License

[Apache License 2.0](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: renasami
• Source: renasami/tegata
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/tegata

Install and usage instructions live in the source repository linked above.