Mcp Opa Authz

mcp-opa-authz

[ci] [Go Reference] [Go Report Card] [License: MIT]

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.

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 permissioncheck. 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 registrationconfig.go             environment, bounds, defaultsargs.go               tool argument decodingtool_opa.go           evaluate_policyopa_capabilities.go   the Rego sandboxauthzen.go            AuthZEN 1.0 wire types and PDP clienttool_authzen.go       authzen_evaluate, _batch, _discovertool_authzen_search.go  authzen_searchscripts/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.0gh 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.