OPA MCP Server

OPA MCP Server

A Model Context Protocol (MCP) serverthat turns any MCP-compatible client (Claude Desktop, Claude Code, Cursor,VS Code, Windsurf, Zed, and others) into a first-classOpen Policy Agent and Rego authoringenvironment.

┌────────────────────┐  MCP / stdio  ┌─────────────────┐  spawn / HTTP  ┌──────────────────┐
│  Claude · Cursor · │ ────────────▶ │  @orygn/opa-mcp │ ─────────────▶ │  opa · regal ·   │
│   VS Code · ...    │ ◀──────────── │                 │ ◀───────────── │  OPA REST API    │
└────────────────────┘   32 tools    └─────────────────┘                └──────────────────┘

Status: v0.1.0. First stable release. Tool surface, error codes, andenvironment variables follow SemVer from thisversion forward.

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 serverruns the real opa fmt and opa parse so output is byte-identical towhat you'd get on the command line, and regal (optional) surfacesidiomatic suggestions.
• Evaluate against data. Run a query against a policy and an inputdocument. Optional --explain, --profile, and --coverage flagssurface execution traces, hot rules, and per-line coverage.
• Debug a deny. rego_explain_decision walks the agent through everyrule that fired (and every one that didn't), so it can answer "why wasthis rejected" without you reading the trace by hand.
• Manage policies on a running OPA. List, get, put, delete policies onan OPA server through its REST API. Works against a localopa run --server or a production deployment with bearer-token auth.
• Build & sign bundles. Package a directory of policies into adeployable bundle, optionally signing it. Output is a regular .tar.gzthe agent can hand to your delivery system.
• Lint. rego_lint runs Regal across a directory or a single fileand returns categorized findings (style, bugs, performance, idioms).

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 avalidated input schema, a structured output envelope, and stable errorcodes, instead of parsing free-form CLI text and inventing its ownfailure taxonomy. That alone makes Rego usable to an agent the way alanguage server makes a language usable to an IDE.
• Higher-level helpers. rego_explain_decision,rego_generate_test_skeleton, rego_describe_policy, andrego_suggest_fix compose the lower-level primitives into the tasksagents are actually asked to do. They don't exist in the OPA CLI.
• Curated knowledge. The bundled MCP resources expose the OPAbuilt-in function catalog, the official Rego style guide (formatted forLLMs), and a curated pattern library covering RBAC, ABAC, Kubernetesadmission, IaC gates, API authz, and rate limiting, so the agent hasauthoritative context without needing to scrape it.
• Safety boundaries the agent can rely on. Path allow-list,subprocess timeouts, response-size caps, and an explicitHTTP_SEND_BLOCKED error for the dangerous OPA built-ins. Defaults areconservative; running the server doesn't quietly grant the agent morereach than the operator intended.

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

Install

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

Claude Desktop / Claude Code

The fastest path is the Smithery one-liner:

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

Or download opa-mcp.mcpb from thelatest releaseand double-click it.

If you prefer to edit claude_desktop_config.json by hand, the snippetlives in 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 thefirst-time install gotchabelow. Windows users substitute C:\\path\\to\\opa.exe.

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 usersettings.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 pinnedversions of opa and regal, and runs as a non-root user. No hostinstall of OPA or Regal is required.

⚠ First-time install gotcha (read this if you used npx or the global install)

If your client's PATH doesn't include the directory where opa lives(this happens with Claude Desktop on Windows and macOS by default), theserver boots fine but every tool call returns OPA_BINARY_NOT_FOUND.

Fix: add OPA_BINARY and REGAL_BINARY env entries to your clientconfig with the absolute path to each binary. The example configs underexamples/ 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 or MCPB install paths; thoseship opa and regal inside the bundle and bypass PATH entirely.See Troubleshooting for full detail.

Configuration

The server reads its configuration from environment variables. Everyvariable is optional; defaults are sensible for a local OPA onhttp://localhost:8181.

Paths in OPA_MCP_ALLOWED_PATHS and the *_BINARY variables must beabsolute. Relative paths and missing binaries are rejected with structurederrors.

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,REGAL_VERSION_TOO_OLD, OPA_UNREACHABLE, OPA_AUTH_FAILED,POLICY_NOT_FOUND, PATH_NOT_ALLOWED, PATH_NOT_FOUND,DEPENDENCY_CONFLICT, NO_TESTS_FOUND, HTTP_SEND_BLOCKED, TIMEOUT,UNKNOWN_ERROR.

Category A: Authoring & static analysis

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

Featured: rego_format

// Input
{
  "source": "package x\nallow{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, andopa bench.

Featured: rego_eval

// Input
{
  "query": "data.rbac.allow",
  "source": "package rbac\nimport rego.v1\nallow if input.role == \"admin\"",
  "input": { "role": "admin" }
}

// Output
{
  "ok": true,
  "data": {
    "result": [{ "expressions": [{ "value": true, "text": "data.rbac.allow", "location": { "row": 1, "col": 1 } }] }]
  }
}

Category C: Bundle operations

Package and sign deployable bundles. Wrap opa build and opa sign.

Category D: OPA server management

Talk to a running OPA server over its REST API. Require OPA_URL topoint at a reachable server.

Category E: Higher-level helpers

The differentiation surface. These compose lower-level primitives intothe tasks agents are actually asked to do.

Prompts

Three MCP promptsship with the server. Clients surface them as slash commands or workflowtemplates.

Resources

Three MCP resourcesexpose curated reference data the agent can read at any time.

Cookbook

A few session shapes that the tool set was designed for.

"Help me write a policy"

You: I need an authz policy: editors can read/write, viewers can only read,
     admins can do anything.

Agent: I'll draft it. (calls rego_format on a draft, then rego_check, then
       rego_lint)

Agent: Here's the policy. I've also generated a test file with cases for
       each role. (calls rego_generate_test_skeleton, then rego_test)

Agent: All 9 tests pass. Want me to save it to <path>?

"Why was this denied?"

You: This API call is being denied and I don't know why.
     [pastes input.json]

Agent: (calls rego_explain_decision against your local policy with that input)

Agent: The deny comes from rule `forbid_anonymous_writes` at line 17.
       Specifically, `input.user` is null and the request method is "POST".
       The rule fires, which causes the default deny. To allow this, you'd
       need either an authenticated user or a policy exception for this
       endpoint.

"Push this policy to staging OPA"

You: Push policies/rbac.rego to the staging OPA server, but first lint and
     test it.

Agent: (rego_lint → 2 style warnings, no errors)
       (rego_test on policies/ → all pass)
       (opa_put_policy with id="rbac" against $OPA_URL)
       (opa_get_policy to verify)

Agent: Done. Policy `rbac` is live on staging at $OPA_URL.

Architecture

┌──────────────────────────────────── @orygn/opa-mcp ───────────────────────────────────┐
│                                                                                       │
│   src/server.ts ──── McpServer (stdio) ─── tool / prompt / resource registries        │
│                          │                                                            │
│                          ├── tools/authoring/         ─┐                              │
│                          ├── tools/evaluation/        ─┤                              │
│                          ├── tools/bundles/           ─┼─── lib/opa-cli.ts ──┐        │
│                          ├── tools/server-management/ ─┤                     │        │
│                          ├── tools/helpers/           ─┘                     │        │
│                          │                                                   ▼        │
│                          │                              lib/subprocess.ts ──┴── opa   │
│                          │                              lib/regal-cli.ts   ───── regal│
│                          │                              lib/opa-client.ts  ───── HTTP │
│                          │                                                            │
│                          └── lib/output.ts (envelope + truncation)                    │
│                              lib/security.ts (path allow-list)                        │
│                              lib/errors.ts (structured failures)                      │
│                              lib/logger.ts (file-only, never stdout)                  │
└───────────────────────────────────────────────────────────────────────────────────────┘

Three things worth knowing if you're going to operate this:

1. stdout is the protocol channel. The server logs to a file vialib/logger.ts and never writes to stdout. If you see stray stdoutbytes, the client disconnects; the MCP transport layer is strict.
2. No tool throws. Every tool catches its own exceptions and returnsa structured { ok: false, error: ... } envelope. The agent sees astable error vocabulary, not a stack trace.
3. Subprocesses are tightly bounded. lib/subprocess.ts runs opaand regal with shell: false, a hard timeout, and SIGTERM-then-SIGKILL escalation. There is no path through the server where anagent can construct a shell command.

Security

This server is designed to run locally, started by an MCP client onthe user's own machine, communicating over stdio. It is not designed tobe exposed on the network.

• File-based tools refuse to read anything outside OPA_MCP_ALLOWED_PATHS.When that variable is unset, file tools return PATH_NOT_ALLOWED.
• Subprocesses run with shell: false and a hard timeout.
• OPA_TOKEN is never echoed in tool responses or log entries.
• Releases are published withnpm provenance;the Docker image is built reproducibly from the committed Dockerfile.

To report a vulnerability, follow SECURITY.md. Pleasedo not open a public issue for security problems.

Troubleshooting

Common issues, fast fixes.

OPA_BINARY_NOT_FOUND even though opa is installed. (most commonfirst-day issue, read this first)

MCP clients (notably Claude Desktop on Windows and macOS) launch theserver with a deliberately reduced PATH that omits user-local bindirectories, even ones that work fine in your interactive shell. Thebinary is on your machine; the spawned MCP server just can't see it.

Find the absolute path to opa:

# macOS / Linux
which opa
# → /usr/local/bin/opa  (or /opt/homebrew/bin/opa, or ~/.local/bin/opa)

# Windows
Get-Command opa | Select-Object -ExpandProperty Source
# → C:\Users\you\bin\opa.exe  (or wherever)

Then set OPA_BINARY to that absolute path in your client's MCP envblock. Same for REGAL_BINARY if you use the rego_lint tool. Theexamples/ configs already include both env vars; justedit the placeholder paths.

This issue does not affect the Docker or MCPB install paths. Thosebundle opa and regal and bypass PATH entirely.

The server starts, then the client says "disconnected."

The most likely cause is something in the process writing to stdoutbesides MCP frames. If you've added a custom tool, check that no libraryit calls prints to stdout. The fixed-position safety net islib/logger.ts. Use it, not console.log.

PATH_NOT_ALLOWED on a file under my project.

OPA_MCP_ALLOWED_PATHS is empty by default. Set it to the absolutepath(s) you want the server to read from, comma-separated.

OPA_UNREACHABLE when calling opa_* tools.

OPA_URL (default http://localhost:8181) must point at a running OPAserver (opa run --server ...). Check with curl $OPA_URL/health.

Regal "version too old."

We track the current Regal release. If REGAL_VERSION_TOO_OLD fires,upgrade Regal: brew upgrade regal or download from theRegal releases page.

directory-package-mismatch violation when linting inline source.

When you pass source rather than paths to rego_lint, Regal sees arandomized temp-file path that can't possibly match your declared packagepath. The diagnostic is an artifact of inline linting, not a real issue.Disable the rule for inline workflows or lint via paths against thereal on-disk file when you want canonical signal.

Where are the logs?

Default location is <OS-tmpdir>/orygn-opa-mcp.log. That's typically/tmp/orygn-opa-mcp.log on Linux/macOS or %TEMP%\orygn-opa-mcp.logon Windows. Set OPA_MCP_LOG_FILE to override, andOPA_MCP_LOG_LEVEL=debug to widen the firehose.

Development

git clone https://github.com/OrygnsCode/opa-mcp-server.git
cd opa-mcp-server
npm install
npm run dev

Common commands:

npm run lint              # ESLint
npm run typecheck         # tsc --noEmit
npm test                  # unit tests (Vitest)
npm run test:coverage     # unit + coverage report
npm run test:integration  # against real opa + regal binaries
npm run build             # compile to dist/

CI runs lint, typecheck, build, and unit tests on every push and PRacross Ubuntu, macOS, and Windows on Node 20 and 22. Integration testsrun on Linux against pinned opa and regal releases.

For the full contributor workflow (adding tools, naming conventions,logging discipline, release process), see CONTRIBUTING.md.

Versioning & support

This project follows Semantic Versioning. The publicsurface for SemVer purposes is the set of registered tools, prompts, andresources, their input/output schemas, the recognized environmentvariables, and the CLI entry point.

Breaking changes will be:

• announced in CHANGELOG.md under a new major version,
• preceded by at least one minor release with a deprecation warning,
• accompanied by a migration note in the release announcement.

Pinned versions of the upstream toolchain (opa and regal) are treatedas part of the build, not as a dependency the operator manages. TheDockerfile, MCPB bundle, and CI all use the same pin; bumps go throughDependabot or a manual PR.

License

MIT © Orygn LLC

@orygn/opa-mcp is an independent project. It is not affiliated with,endorsed by, or sponsored by the Open Policy Agent project, the CloudNative Computing Foundation, Styra, or Anthropic. "Open Policy Agent"and "Rego" are trademarks of their respective owners. "Model ContextProtocol" is a trademark of Anthropic, PBC.