Skip to main content

Herald, the authorization MCP server

Objective​

Explain what Herald is (the authorization MCP server) and what it is not (a PDP), and describe how an MCP client asks Herald for an authorization decision as a tool call.

Concept​

Herald is the evaluate product of the AI Security Fabric. It exposes authorization as tools over the Model Context Protocol (MCP). An AI agent, or any MCP client, can call a Herald tool to ask "may this subject take this action on this resource" and get an allow or deny answer, instead of embedding that logic in the agent's own code.

Why this matters for agents specifically: an autonomous agent chains actions and reaches across systems. If each step's access check is hard-coded, the checks drift, they are invisible to review, and they cannot use fresh context. Fronting the check as an MCP tool means every agent asks the same governed question the same way, and the answer is produced from policy rather than from the agent's assumptions.

Keep the boundaries straight, because they are easy to blur:

  • Herald is the MCP server that presents the authorization question as a tool. It is the interface an agent talks to.
  • Herald is not the PDP. The policy is still evaluated by OPA or Enterprise OPA. Herald hands the query to the decision engine and returns the result.
  • Herald is not the control plane. That is Writ, which governs and deploys the policies. Herald evaluates against them.

So a single request flows like this: agent -> Herald tool call over MCP -> policy evaluated by OPA/Enterprise OPA -> allow or deny -> back to the agent.

flowchart LR
  A[AI agent / MCP client] -->|MCP tool call: check access| H[Herald: authorization MCP server]
  H -->|query + federated context| PDP[OPA / Enterprise OPA]
  PDP -->|allow / deny| H
  H -->|decision| A

Text version of the diagram: an AI agent calls a Herald tool over MCP; Herald assembles the query with federated context and hands it to the PDP (OPA or Enterprise OPA); the PDP returns allow or deny; Herald returns that decision to the agent. Herald is the tool surface, not the decision engine.

One more property to hold onto for the next lesson: throughout this course we model a Herald tool that holds a read-only scope. Treat that as a teaching model, not a stated product tier. Under that model the tool can answer authorization questions but cannot change anything, and that single constraint decides which actions the tool is even able to reason about, which is the subject of lesson 3.

Hands-on lab​

The lab in ../lab/policy.rego is the policy behind a Herald authorization tool. It is standard OPA: default deny, with input shaped like the query a Herald tool would evaluate. Read it once now to see the shape of the decision Herald fronts, then run the suite to confirm the decision engine agrees:

git clone https://github.com/EnforceAuth/university-labs.git
cd university-labs
opa test courses/evaluate-with-herald -v

Run it from the cloned university-labs repo. Expected: PASS: 8/8.

You are running opa directly here, not Herald. That is deliberate and honest: Herald is the MCP surface, and OPA or Enterprise OPA is the engine that returns the decision. In a real deployment the same policy would be evaluated behind a Herald tool call, and your agent would receive the identical allow or deny.

To picture the real Herald exercise without faking it: an MCP client (an agent, or an MCP-aware IDE) lists Herald's tools, calls the authorization tool with the subject, action, and resource, and reads back the decision. Under the read-only scope we model here, the client can ask but not mutate. Do not expect an enforceauth run command or any local Herald CLI in this lab; there is none. The gradable artifact is the policy, evaluated by opa test.

Check for understanding​

  1. An agent needs to decide whether it may read a dataset before acting. Which product does it call, over which protocol, and which component actually evaluates the policy?
  2. True or false: Herald is the PDP that returns the allow or deny decision. Explain your answer.
  3. This course models a Herald tool that holds a read-only scope. Under that model, what does the scope let a tool do versus not do?