OPA MCP Server

A Model Context Protocol (MCP) server that turns any MCP-compatible client (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, and others) into a first-class Open Policy Agent and Rego authoring environment.

+--------------------+ MCP/stdio  +-----------------+ spawn/HTTP +---------------------+
|  Claude · Cursor · |----------> | @orygn/opa-mcp  |----------> | opa · regal         |
|   VS Code · ...    |<---------- |                 |<---------- | conftest · REST API  |
+--------------------+  52 tools  +-----------------+            +---------------------+

Status: v0.6.0. Tool surface, error codes, and environment variables follow SemVer from v0.1.0 forward.

Upgrading to 0.6.0: rego_bench reports iterations, nsPerOp, allocsPerOp and bytesPerOp. The fields opa prints (N, T, Bytes, MemAllocs, MemBytes, Extra) were top-level and now sit under raw for a single run, so anything that read them from the top level has to look there. With count above one, raw is omitted: every document is in runs, and fastest indexes the one the top-level figures come from.

Upgrading to 0.4.0: subprocesses no longer inherit the server's environment. A policy that read a variable through opa.runtime().env will no longer see it; name the variable in OPA_MCP_PASSTHROUGH_ENV if it is genuinely needed. See the security section for why.

Upgrading to 0.3.0: the bundled OPA is now 1.19, so Rego v0 policies no longer parse (if is required before a rule body, contains before a partial set). Run rego_migrate_v1 to convert them. If you supply your own binary via OPA_BINARY or PATH, nothing changes.

---

Table of contents

• What you can do with it
• Why this MCP
• Install
• Configuration
• Tool reference
• Prompts
• Resources
• Cookbook
• Architecture
• Security
• Troubleshooting
• Development
• Versioning & support
• License

What you can do with it

Once an MCP client is connected, an agent can:

• Author Rego. Generate, format, and refactor policies. The server runs the real opa fmt and opa parse so output is byte-identical to what you'd get on the command line, and regal (optional) surfaces idiomatic suggestions.
• Evaluate against data. Run a query against a policy and an input document. Optional --explain, --profile, and --coverage flags surface execution traces, hot rules, and per-line coverage.
• Debug a deny. rego_explain_decision walks the agent through every rule that fired (and every one that didn't), so it can answer "why was this rejected" without you reading the trace by hand.
• Manage policies on a running OPA. List, get, put, delete policies on an OPA server through its REST API. Works against a local opa run --server or a production deployment with bearer-token auth.
• Build & sign bundles. Package a directory of policies into a deployable bundle, optionally signing it. Output is a regular .tar.gz the agent can hand to your delivery system.
• Lint. rego_lint runs Regal across a directory or a single file and returns each finding with its category, level and location.

A walk-through of a typical session lives in Cookbook.

Why this MCP

OPA already has a perfectly good CLI and REST API. So why an MCP wrapper?

• Schema-shaped tool surface. An agent calling rego_eval gets a validated input schema, a structured output envelope, and stable error codes, instead of parsing free-form CLI text and inventing its own failure taxonomy. That alone makes Rego usable to an agent the way a language server makes a language usable to an IDE.
• Higher-level helpers. rego_explain_decision, rego_generate_test_skeleton, rego_describe_policy, and rego_suggest_fix compose the lower-level primitives into the tasks agents are actually asked to do. They don't exist in the OPA CLI.
• Curated knowledge. The bundled MCP resources expose the OPA built-in function catalog, the official Rego style guide (formatted for LLMs), and a curated pattern library covering RBAC, ABAC, Kubernetes admission, IaC gates, API authz, and rate limiting, so the agent has authoritative context without needing to scrape it.
• Safety boundaries the agent can rely on. Path allow-list, subprocess timeouts, and response-size caps. Defaults are conservative; running the server doesn't quietly grant the agent more reach than the operator intended.

If you've ever watched an agent fight opa eval's argument order, you'll recognize the gap this fills.

Install

The server runs locally over stdio. Pick the install path that matches your client.

Claude Desktop

Edit claude_desktop_config.json directly (or copy from examples/claude-desktop.json):

{
  "mcpServers": {
    "opa": {
      "command": "npx",
      "args": ["-y", "@orygn/opa-mcp"],
      "env": {
        "OPA_BINARY": "/usr/local/bin/opa",
        "REGAL_BINARY": "/usr/local/bin/regal",
        "OPA_URL": "http://localhost:8181",
        "OPA_MCP_ALLOWED_PATHS": "/path/to/your/policies"
      }
    }
  }
}

Replace the /usr/local/bin/... paths with your real ones. See the first-time install gotcha below. Windows users substitute C:\\path\\to\\opa.exe.

Or download opa-mcp.mcpb from the latest release and double-click it.

Alternatively, use the Smithery one-liner:

npx -y @smithery/cli install @orygn/opa-mcp --client claude

Claude Code (CLI)

Register the server for the current project with claude mcp add:

claude mcp add \
  --env OPA_BINARY=/usr/local/bin/opa \
  --env REGAL_BINARY=/usr/local/bin/regal \
  --env OPA_MCP_ALLOWED_PATHS=/path/to/your/policies \
  opa -- npx -y @orygn/opa-mcp

This writes the config into .mcp.json at your project root and is picked up automatically on every claude session in that directory. Add --scope user to register it globally instead.

Replace the paths with your real absolute paths (same caveat as Claude Desktop above). On Windows use C:\path\to\opa.exe syntax.

Persistent context and auto-checks for policy repos. If you work in an OPA policy repo regularly, two extra files remove repetitive setup from every session:

• examples/CLAUDE.md -- copy to your repo root or .claude/CLAUDE.md. Claude Code loads it every session, so the agent always knows which tools to use and what conventions apply.
• examples/claude-code-hook.json -- merge the hooks block into .claude/settings.json. Runs opa check automatically after any .rego file is written, so syntax errors surface immediately without a manual tool call.

Cursor

Drop examples/cursor.json into either .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped).

VS Code (GitHub Copilot Chat)

Drop examples/vscode.json into .vscode/mcp.json, or paste the servers block into your user settings.json under mcp.servers.

Windsurf, Zed, and others

See examples/ for a full set of drop-in configs.

Manual install (any MCP client)

npm install -g @orygn/opa-mcp
opa-mcp --version

then point your client at the opa-mcp binary.

Docker

docker pull orygn/opa-mcp:latest
docker run --rm -i \
  -v /path/to/your/policies:/policies:ro \
  -e OPA_MCP_ALLOWED_PATHS=/policies \
  orygn/opa-mcp

The image is multi-arch (linux/amd64, linux/arm64), bundles pinned versions of opa and regal, and runs as a non-root user. No host install of OPA or Regal is required.

⚠ If every tool call returns OPA_BINARY_NOT_FOUND

The npm package carries its own opa for the five platforms it is built for, so a client PATH without opa on it does not matter there. The MCPB has no bundled copy, and on any other platform neither does npm: then the server boots but every tool call returns OPA_BINARY_NOT_FOUND. Neither the npm package nor the MCPB bundles regal or conftest, and the Docker image ships regal but not conftest, so their tools need a PATH entry or an explicit path either way.

Fix: add OPA_BINARY and REGAL_BINARY env entries to your client config with the absolute path to each binary. The example configs under examples/ ship with placeholder paths you replace. Find the real paths with:

which opa && which regal                                    # macOS / Linux

Get-Command opa, regal | Select-Object Source              # Windows

This does not affect the Docker install path, which ships opa and regal in the image and bypasses PATH entirely. The MCPB bundle carries neither, and unlike the npm install has no bundled fallback: set OPA_BINARY or put opa on PATH. See Troubleshooting for full detail.

Configuration

The server reads its configuration from environment variables. Every variable is optional; defaults are sensible for a local OPA on http://localhost:8181.

Variable	Default	Purpose
OPA_URL	http://localhost:8181	Base URL of an OPA REST endpoint, used by opa_* tools.
OPA_TOKEN	(unset)	Bearer token for OPA, if your instance requires auth. Treated as a secret. Never echoed in logs or tool responses.
OPA_BINARY	opa (on PATH)	Path to the opa CLI, used by rego_* tools.
REGAL_BINARY	regal (on PATH)	Path to the regal linter. Required by rego_lint, rego_fix, and rego_security_audit.
CONFTEST_BINARY	conftest (on PATH)	Path to the conftest binary. Only required by conftest_* tools. Returns CONFTEST_NOT_FOUND if absent.
OPA_MCP_ALLOWED_PATHS	(unset)	Comma- or semicolon-separated list of directories the server is allowed to read policies from. When unset, file-based tools refuse to read from disk.
OPA_MCP_LOG_FILE	<tmpdir>/orygn-opa-mcp.log	Path the server appends logs to. The server never writes to stdout; that channel is reserved for the MCP protocol.
OPA_MCP_LOG_LEVEL	info	One of debug, info, warn, error.
OPA_MCP_MAX_RESPONSE_BYTES	100000	Hard cap on a single tool response. Larger payloads are truncated with a __truncated: true marker. Values below 512 are refused.
OPA_MCP_TIMEOUT_MS	30000	Hard timeout for any spawned subprocess (opa, regal). After this, the child gets SIGTERM and then SIGKILL.
OPA_MCP_HTTP_TIMEOUT_MS	15000	Timeout for each request to the OPA REST API, from the connection attempt to the last byte of the response; reported as TIMEOUT.
OPA_MCP_NO_TELEMETRY	(unset)	Set to 1 to disable the anonymous startup ping. The ping sends the server version, OS platform, and a random install ID. The install ID is stored at ~/.orygn/opa-mcp/install-id and is generated once on first run. No policy content or file paths are ever sent.
OPA_MCP_MAX_SUBPROCESS_BYTES	33554432 (32 MiB)	Maximum bytes captured from a subprocess's stdout and stderr, counted separately. On overflow the stream is clamped, the child is stopped, and the tool returns OUTPUT_TOO_LARGE. Distinct from OPA_MCP_MAX_RESPONSE_BYTES, which trims the reply after the output is already in memory.
OPA_MCP_PASSTHROUGH_ENV	(unset)	Comma-separated variable names to pass through to opa, regal and conftest. Everything else is withheld. Anything named here is readable by any policy the server evaluates, via opa.runtime().env, so use it only for values that are safe in that position.
OPA_MCP_BLOCK_ENV	(unset)	Comma-separated variable names to withhold from opa, regal and conftest even when they are on the built-in allow-list. Applied last, so it also overrides OPA_MCP_PASSTHROUGH_ENV. Use it to drop the proxy variables, which can carry credentials, at the cost of proxy support.

Paths in OPA_MCP_ALLOWED_PATHS must be absolute, and a *_BINARY value is either a bare command name looked up on PATH or an absolute path; anything else stops the server at startup. A binary that cannot be run is reported by each tool call with a structured error.

Tool reference

Every tool returns a JSON envelope:

{ "ok": true, "data": { ... }, "warnings": [ ... ] }
{ "ok": false, "error": { "code": "INVALID_REGO", "message": "...", "hint": "...", "details": { ... } } }

Stable error codes: INVALID_INPUT, INVALID_REGO, INVALID_BUNDLE, EVAL_ERROR, OPA_BINARY_NOT_FOUND, REGAL_NOT_FOUND, CONFTEST_NOT_FOUND, OPA_UNREACHABLE, OPA_AUTH_FAILED, POLICY_NOT_FOUND, DATA_NOT_FOUND, PATH_NOT_ALLOWED, PATH_NOT_FOUND, NO_TESTS_FOUND, COVERAGE_BELOW_THRESHOLD, OPA_VERSION_UNSUPPORTED, GITHUB_TOKEN_MISSING, GIST_CREATE_FAILED, OUTPUT_TOO_LARGE, SUBPROCESS_KILLED, OPA_URL_INVALID, TIMEOUT, CANCELLED, UNKNOWN_ERROR.

Category A: Authoring & static analysis

Operate on Rego source code without needing a running OPA server. Wrap opa fmt, opa parse, opa check, opa inspect, opa capabilities, opa deps, and regal.

Tool	What it does
rego_format	Format Rego source. Wraps opa fmt. Idempotent.
rego_check	Type-check and validate Rego. Wraps opa check.
rego_lint	Run Regal across a file or directory. Returns each violation with its category, level and location. Requires regal on PATH or REGAL_BINARY set.
rego_parse_ast	Parse Rego to AST JSON. Wraps opa parse.
rego_inspect	Inspect a bundle or directory: packages, rules, annotations. Wraps opa inspect.
rego_capabilities	List the built-ins and features the resolved opa binary understands (OPA_BINARY, then PATH, then the bundled copy); builtins names up to 100 to return full records for
rego_deps	Static dependency analysis: rule-level data references and cross-package calls.
rego_migrate_v1	Migrate Rego v0 source to v1 syntax. Runs opa fmt --rego-v1 then validates with opa check --v1-compatible. Returns { original, migrated, changed, valid, errors }.
rego_check_schema	Check Rego against a JSON Schema. Validates that every input.* field the policy reads exists in the schema using opa check --schema. Accepts an inline schema, a path to a JSON Schema file, or a schema directory when the policy declares schemas: annotations.

Featured: rego_format

// Input
{
  "source": "package x\nallow if input.user==\"admin\""
}

// Output (ok)
{
  "ok": true,
  "data": {
    "formatted": "package x\n\nallow if input.user == \"admin\"\n",
    "changed": true
  }
}

Featured: rego_check

// Input
{
  "source": "package x\nallow if y",
  "strict": true
}

// Output (error path; the JSON diagnostics arrive on stderr from opa)
{
  "ok": true,
  "data": {
    "valid": false,
    "errors": [
      {
        "code": "rego_unsafe_var_error",
        "message": "var y is unsafe",
        "location": { "row": 2, "col": 11 }
      }
    ]
  }
}

Category B: Evaluation & testing

Run a query against a policy and input. Wrap opa eval, opa test, and opa bench.