mcp-opa-authz

Stop letting your agent guess at authorization. This is an MCP server that answers "is this allowed?" from real policy code — either Rego you hand it, or the OpenID AuthZEN 1.0 PDP that actually governs your system.

Ask a model whether Alice may delete that document and it will produce a confident, plausible, unfalsifiable answer. Give it these tools and the answer comes from the policy.

brew install kanywst/tap/mcp-opa-authz
# or, without Homebrew:
go install github.com/kanywst/mcp-opa-authz@latest

claude mcp add opa-authz -- mcp-opa-authz

That is enough for evaluate_policy. Point it at a PDP to get the rest:

claude mcp add opa-authz \
  --env AUTHZEN_PDP_URL=http://localhost:8181/access/v1/evaluation \
  -- mcp-opa-authz

Two layers, same question

Use evaluate_policy while authoring or debugging a policy you have the source of. Use authzen_evaluate when the decision has to come from production, not from a policy pasted into the chat. The server's MCP instructions tell the model the same thing, so it usually picks correctly on its own.

Related MCP server: enterprise-auth-mcp-server

What makes this different from opa eval in a shell tool

An agent given shell access can already run opa eval. What it cannot do is get an answer it is allowed to trust:

• Undefined is not false. A Rego query with no matching rule and no default returns []. Every model reads that as a deny. evaluate_policy returns defined alongside value, so "the policy denied" and "the policy has no opinion" stop being the same answer.

• A PDP that did not answer is not a deny. AuthZEN makes decision a required member. A response missing it decodes into a Go bool as false — a broken PDP would look like a strict one. This server treats a missing decision as a failure, never as a deny. Same for a 401: that means this server failed to authenticate, not that the subject was denied, and the error says so.

• The policy runs in a sandbox. Rego handed to an MCP server was written by a model, from text that may have come from a web page. OPA's http.send would let that policy make arbitrary HTTP requests from your laptop, and opa.runtime() would hand it your environment. Both are compiled out. See Security.

• Batch decisions carry their index. permit_on_first_permit legitimately returns fewer decisions than you sent. Zipping the arrays would attach a decision to the wrong resource.

• An empty search is not a failed search. results: [] means nothing is permitted; a response with no results member, or a result of the wrong entity type, is an error.

Demo

Debugging a policy that is denying when it should not:

> Why is bob getting denied on doc-1? Here's the policy and the input.

  evaluate_policy(rego=…, query="data.rbac.allow", input_json=…, trace=true)

  {
    "defined": true,
    "value": false,
    "printed": ["checking roles for", "bob"],
    "trace": [
      "Enter data.rbac.allow",
      "| Eval some role in roles[input.user]",
      "| Fail roles[\"bob\"]",
      …
    ]
  }

Bob has no entry in `roles` at all — the rule never reaches the permission
check. Adding "bob": {"viewer"} fixes it.

Then confirming against the PDP that actually runs:

> Does production agree?

  authzen_evaluate(subject={"type":"user","id":"bob"}, …)

  { "decision": false, "context": { "reason": "no role binding" },
    "request_id": "3f9c…", "pdp_url": "https://pdp.internal/access/v1/evaluation" }

Tools

evaluate_policy

Returns defined, value, the raw OPA result_set (omitted with result_set_omitted past 256 KiB encoded), any print() output (200 lines of 1 KiB), and the trace when asked for.

authzen_evaluate

Returns decision, the PDP's context if any, the pdp_url that answered, and the request_id sent as X-Request-ID — so a decision in a transcript can be found in the PDP's logs.

authzen_evaluate_batch

Same arguments, plus evaluations (a JSON array whose entries override the top-level defaults) and evaluations_semantic (execute_all, deny_on_first_deny, permit_on_first_permit). Capped at 100 entries per call. Without pdp_url, the endpoint is the access_evaluations_endpoint the PDP advertises in its metadata, or /access/v1/evaluations under the root of AUTHZEN_PDP_URL when it advertises none — the same resolution, cache and same-origin rule as authzen_search. endpoint_source in the result says which was used.

{
  "subject": "{\"type\":\"user\",\"id\":\"alice\"}",
  "action": "{\"name\":\"read\"}",
  "evaluations": "[{\"resource\":{\"type\":\"doc\",\"id\":\"1\"}},{\"resource\":{\"type\":\"doc\",\"id\":\"2\"}}]"
}

authzen_search

The AuthZEN Search APIs. search picks which entity is being listed; that entity carries only its type.

context, pdp_url, page_limit and page_token are optional. Without pdp_url, the endpoint is the one the PDP advertises in its metadata (search_subject_endpoint etc.), as the specification requires, falling back to the default path (/access/v1/search/{subject,resource,action}) under the root of AUTHZEN_PDP_URL when it has no usable metadata. The metadata is cached per PDP for five minutes, and endpoint_source in the result says which one was used. An advertised endpoint has to be on the PDP's own origin, because the PDP token goes with the request; a cross-origin one is refused unless passed explicitly as pdp_url. Returns results, has_more and next_page_token; pass the token back as page_token, with every other argument unchanged, for the next page. A response whose page object has no next_token is an error even though the specification's own example has one: without it nothing says whether the list is complete.

{
  "search": "resource",
  "subject": "{\"type\":\"user\",\"id\":\"alice\"}",
  "action": "{\"name\":\"read\"}",
  "resource": "{\"type\":\"document\"}"
}

authzen_discover

Fetches /.well-known/authzen-configuration from a PDP root. pdp_url may be a root or an evaluation endpoint — the known AuthZEN path suffix is stripped. For a PDP mounted under a prefix, the well-known string goes between the host and the prefix, as RFC 8615 and the specification place it (https://gw.example.com/.well-known/authzen-configuration/pdp); the older appended form (…/pdp/.well-known/authzen-configuration) is tried if that 404s. A document whose policy_decision_point is not the root it was fetched from is rejected, as the specification requires.

Standards conformance

Implements Authorization API 1.0, approved as an OpenID Final Specification in January 2026:

Related work worth knowing about: the AuthZEN working group's COAZ profile binds AuthZEN to MCP tool calls themselves, so a gateway can authorize tools/call with an x-authzen-mapping declared in a tool's inputSchema. That is the enforcement side of the same problem — this server is the inspection side, and the two compose.

Configuration

A malformed value stops the server at startup rather than being silently replaced by the default — a bound an operator believes is in place should be in place.

Security

evaluate_policy compiles and runs Rego that a model produced, inside this process. Three OPA built-ins are removed from the capability set for that reason:

Time, JWT, UUID and random built-ins are untouched — those appear in real authorization policies. A policy using a removed built-in fails to compile with a message naming it, and pointing at MCP_OPA_ALLOW_NETWORK_BUILTINS for the cases where you genuinely want it.

The PDP client is constrained too: pdp_url must be an absolute http(s) URL with a host and no userinfo, redirects are refused rather than followed with the Authorization header attached, responses are read through a byte cap, and PDP error bodies are truncated before they reach the model's context.

Reporting a vulnerability: see SECURITY.md.

Running it

From source

make smoke

Builds the binary, stands up a fake AuthZEN PDP, drives one real MCP stdio session through all five tools, and asserts each answered — including that http.send is still rejected. No MCP client and no real PDP needed.

Container

docker run -i --rm \
  -e AUTHZEN_PDP_URL=https://pdp.example.com/access/v1/evaluation \
  ghcr.io/kanywst/mcp-opa-authz

Cursor and other MCP clients

{
  "mcpServers": {
    "opa-authz": {
      "command": "mcp-opa-authz",
      "env": { "AUTHZEN_PDP_URL": "http://localhost:8181/access/v1/evaluation" }
    }
  }
}

A local opa-authzen-plugin on :8181 works as the PDP. So does Topaz, Cerbos, Keycloak with its experimental AuthZEN support, or anything else on the interop list.

Examples

examples/ has reference Rego policies for evaluate_policy:

• rbac.rego — role to permission mapping

• abac.rego — clearance level comparison

• k8s_admission.rego — admission control: required labels

Layout

Flat on purpose. A single-binary MCP server does not need cmd/, internal/ or pkg/.

main.go               server bootstrap, CLI, tool registration
config.go             environment, bounds, defaults
args.go               tool argument decoding
tool_opa.go           evaluate_policy
opa_capabilities.go   the Rego sandbox
authzen.go            AuthZEN 1.0 wire types and PDP client
tool_authzen.go       authzen_evaluate, _batch, _discover
tool_authzen_search.go  authzen_search
scripts/smoke.sh      end-to-end MCP session

Verifying a release

Releases ship a cosign-signed checksum file (Sigstore keyless via GitHub OIDC) and a CycloneDX SBOM per archive. The signature and its certificate travel together in one Sigstore bundle, *-checksums.txt.sigstore.json.

TAG=v0.3.0
gh release download "$TAG" -R kanywst/mcp-opa-authz -p '*-checksums.txt*'

cosign verify-blob \
  --bundle "mcp-opa-authz-${TAG#v}-checksums.txt.sigstore.json" \
  --certificate-identity-regexp 'https://github.com/kanywst/mcp-opa-authz/.github/workflows/release.yml@refs/tags/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  "mcp-opa-authz-${TAG#v}-checksums.txt"

Then check the archive you downloaded against that file:

sha256sum -c "mcp-opa-authz-${TAG#v}-checksums.txt" --ignore-missing

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Good first contributions: another example policy, a PDP this has not been tried against, or a gap against the AuthZEN text.

This repo is the merge of the former 0-draft/mcp-opa and 0-draft/mcp-authzen. Both histories are preserved here.

License

MIT. See LICENSE.